O'Reilly logo

Code Craft by Pete Goodliffe

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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 ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required