Comments

Most programming languages have a facility for adding informal text to the source text of programs: comments. Comments have an obvious role in aiding the reader of a program (even the most mnemonic identifiers cannot tell the whole story). Effective commenting requires long practice, and a good feel for the kind of detail that the reader needs.

It is not appropriate to use a vast amount of comment text; that can be as bad as none at all. The intelligent reader needs signposts and hints - not impenetrable detail, nor a wilderness.

One important point before discussing commenting style in detail:

What should comments contain?

Comments have two important roles:

1. They can be used to explain the purpose of programs, or fragments thereof. This is the main role. A comment of this kind is useful to a reader who is trying to grasp structure and general concepts, and to a reader who is trying to answer the question "Do I need to be looking at this any more carefully?"
2. They can be used to explain the technical details of programs, or fragments thereof. However, in many ways program code represents its own "blow-by-blow" details much better than any comment can (and much more concisely), so this kind of comment should be used cautiously. It is probably best to restrict them to general statements about the details involved, and let the intelligent reader work out from the code what is actually happening. For example:

   // The algorithm used is search with sentinel
   // Scan salesTable looking for any zeros
   // Check whether x is in range 
   

• For a program:

  // Processes marks and reports final grades 
  

  describes purpose, and

  // Each student is represented by an object of class MarkRecord
  // The results are stored in an array of ClassRecords
  

  is a useful hint about internal workings, but not in unnecessary detail.

• For a method or section of code within a method:

  // Prints the contents of the database in alphabetic order
  

  describes purpose, whereas

  // Copy array telNumbers into tempNumbers.
  // Bubblesort tempNumbers into alphabetic order.
  // Then output the entries in tempNumbers on successive lines.
  

  describes the mechanism.

Note: Comments should never just re-state what is evident from the program code itself. The following, for example, are pointless:

car = car+1;             // Add one to cars
g.drawRect(50,50,10,20); // Call drawRect with parameters 50,50,10,20

Better would be purpose oriented comments:

car = car+1;             // One more sold 
g.drawRect(50,50,10,20); // Draw the chimney

Where should comments go?

Programs:

Should have an introductory comment stating the purpose of the program, and what facilities it provides. This may be followed by a paragraph with a judicious summary of important technical detail. Also useful to include date and author's name, and maybe a history of updates. For example:

// Processes marks and reports final grades

// Each student is represented by an object of class MarkRecord
// The results are stored in an array of ClassRecords

// Fred Bloggs  March 1995
// John Doe June 1996: Standard deviation calculation added 

Each variable declaration

should have a comment (usually brief, and alongside it) describing the role of the variable.

Methods

should have fairly comprehensive comments at the start (before or after the header). These comments should describe the purpose, effect or result of a call of the method, in particular as it is related to (and determined by) the parameters and any non-local variables referred to by the body of the method. They should describe the roles of the individual parameters. What the method does should be described explicitly in terms of the formal parameter names. Sometimes a brief additional statement of the technical details of the method's internal working can be helpful - in a separate paragraph.

For example, to illustrate these ideas:

private void find(TelNumber[] directory, int theNumber) {
  // This method searches for the telephone number theNumber in 
  // directory. 
  // A message is written out indicating 
  // whether or not theNumber was found.
       
  // Uses linear search with a sentinel. 
  ...
}

It can be a useful practice to put a comment at the end of each method body indicating which method it is the end of. (Some programming languages enforce this!)

Within program code itself

comments can be used to state the purpose of the code: introducing sections, or giving hints about individual statements. These can be placed on a separate line, indented to align with the code itself, or on the same line as the code and to the right.

These comments should be brief, and certainly not on every line. The style of comments should again be to help the reader to understand the purpose of the commented statements; a comment which simply says what can be read from the program code itself is no use.