Commenting loops and conditionals
Loops and conditionals should be commented like regular code and functions. Numbering loops to identify them later is somewhat extreme. A better approach is to use a folding editor, which can show a whole loop as one line upon folding the loop (lines between folding marks are hidden but not gone). Think of folding marks like XML/HTML begin/end tags, which are possible to nest. Your favorite editor may support folding already. (X)Emacs does, either with Outline or with folding.el modes.
Listing 10
|
Always state the purpose and bounds of the loop. For example, "count from 2 to 200" is fine, but "process array" is not. If logical conditions affect the bounds, state them as well, but not at the top of the loop. The summary at the top of the loop should not note exceptions to the general iteration, unless they are very important to the loop. Let discretion be your guide.
View Road to better programming: Chapter 2. Commenting your code Discussion
Page: 1 2 3 4 5 6 7 8 Next Page: Commenting the final stages of the program