Code Craft

Working with Comments

Comments are convenient tools to use while you are writing code. But be careful not to abuse them.

Helping You to Write Routines

A common routine-writing approach is to fashion its structure in comments first and then fill in the code underneath each comment line. If you work this way, you should ask yourself, once finished, whether the remaining comments are still useful. Evaluate them against the criteria just discussed, and revise or remove them if necessary. Don’t just leave them and move on.

The alternative is to write the new routine freehand, and then add any necessary comments afterward. The danger is that you’ll forget to finish the job, or that you might not write the best comments—now knowing almost too well how the ...