Skip to Main Content
Code Craft
book

Code Craft

by Pete Goodliffe
December 2006
Intermediate to advanced content levelIntermediate to advanced
610 pages
22h 58m
English
No Starch Press
Content preview from Code Craft

What Goes Inside Our Comments?

Of writing well the source and fountainhead is wise thinking.

Horace

Bad comments are worse than no comments at all—they will misinform and mislead the reader. So what sort of thing should you write in comments? Here are a few basic steps to improve the quality of your comment content:

Explain Why, Not How

This is a key point, so read this paragraph twice. Then eat the page. Your comments should not describe how the program works. You can see that by reading the code. After all, the code is the definitive description of how the code works. And it has been written clearly and comprehensibly, hasn’t it? You should instead focus on describing why something is written the way it is or what the next block of statements ultimately ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.
Start your free trial

You might also like

Write Great Code, Volume 2, 2nd Edition

Write Great Code, Volume 2, 2nd Edition

Randall Hyde
The Art of Clean Code

The Art of Clean Code

Christian Mayer

Publisher Resources

ISBN: 9781593271190Errata