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