Next: About this document Up: Comments Previous: Comments

What should comments contain?

Comments have two important roles:

Here are some examples of the distinction between these two kinds of comments:

Where should comments go?
Here are some general principles:

Program and module files
should have an introductory comment saying what the purpose of the program or module is, and what facilities it provides. This may be followed by a paragraph with a judicious amount of technical detail. Also useful to include date and author's name.

Each variable declaration, type definition, and record field identifier
should have a comment (usually brief, and alongside it) describing the role of the variable, type, etc.

Procedures and functions
should have fairly comprehensive comments at the start (before or after the procedure/function heading). These comments should describe the purpose, effect or result of a call of the procedure/function, in particular as it is related to (and determined by) the parameters and any global variables referred to by the body of the procedure/function. They should describe the roles of the individual parameters, and whether each is In, Out or In/Out. What the function/procedure does should be described explicitly in terms of the formal parameter names. Sometimes a brief additional statement of the method used can be helpful, again in a separate paragraph.

For example, to illustrate these ideas:

       procedure Find(var Directory : Tel_Numbers; Item : Tel_No);
       (* In: Directory, Item.

          This procedure searches for the telephone number Item in the given
          Directory. Note that the final entry in the Directory is indicated
          by the global variable Top. A message is written out indicating 
          whether or not Item was found.
          Uses linear search with a sentinel. *)
It is a useful practice to put a comment at the end of each procedure/function body indicating which procedure/function 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.

For example:

       (* Now count cars into the car park *)
       Level1:=Level1+1;  (* One more car onto level 1 *)

Some programmers like to mark the end of if statements and of loop bodies with a short comment to the right of the end where a compound statement has been used. For example:

       if .... then
         end (* if *)
This is certainly helpful if the compound statement is long and has many indented subcomponents; it is obviously related to the practice of marking the end of procedure/function bodies with a comment - but it is not always obvious which if, etc. it is marking the end of.

Next: About this document Up: Comments Previous: Comments

Simon Jones (