Next: About this document
Comments have two important roles:
Here are some examples of the distinction between these two kinds of
- 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
- 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
- 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
- Each variable declaration, type definition, and record field
- 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
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
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
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.
(* 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