Developer Forums | About Us | Site Map
Search  
HOME > TUTORIALS > SERVER SIDE CODING > PERL TUTORIALS > ROAD TO BETTER PROGRAMMING: CHAPTER 2. COMMENTING YOUR CODE


Sponsors





Useful Lists

Web Host
site hosted by netplex

Online Manuals

Road to better programming: Chapter 2. Commenting your code
By Teodor Zlatanov - 2004-02-11 Page:  1 2 3 4 5 6 7 8

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


# go through all the numbers between 2 and 200, and print a message
# for each one
foreach my $counter (2 .. 200) 
{
  print "Whoa, the counter is $counter!\n";
}

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

First published by IBM developerWorks


Copyright 2004-2017 GrindingGears.com. All rights reserved.
Article copyright and all rights retained by the author.