What should comments contain?

Comments have two important roles:

• They can be used to explain the purpose of programs, modules 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 ``Is this of any use to me?''
• They can be used to explain the technical details of programs, modules 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 (e.g. (* The algorithm used is search with sentinel *) ), and such comments should never just re-state what is evident from the program code itself (e.g. (* Assign 2*Y to X *) ).

  6inThis kind of comment is useful only to someone who needs to understand operational details. Often this kind of comment appears as an adjunct to a ``purpose'' comment (for example, at the start of a program or procedure, see below) - but in this case it should be should be physically separate, usually in a paragraph following the purpose comment.
  Keep the issues separated, to help the two kinds of reader.

• For a procedure or major section of program: (* Prints the contents of the database in alphabetic order *) describes purpose, whereas (* Uses a for loop to scan the arrays A, B and C, printing out the values *) describes the mechanism.
• Within program code itself: commenting tex2html_html_special_mark_quotCars:=Cars+1" with (* Adds one to Cars *) is uninformative, whereas (* One more car has entered the car park *) may be helpful. Another example: commenting if Width>0 then with (* Is Width>0 ? *), doesn't help, whereas (* Is Width valid for drawing? *) is helpful.

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
         begin
         ...
         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.