CS Department
Documentation Standards

Last revised: March 2001

Synopsis

The following is a description of expected program documentation. See also the Program Style Guide.

Comments

Comments allow us to write in natural language to clarify the intent of the program. Comment programs internally with clear, coherent statements in concise English, using good grammar, punctuation, and spelling. You might try writing the comments first, then the program to comply with the comments.

What comments should always be in a program?

At the beginning ...
In the declaration section ...
For each section ...

Header Comments

At the beginning of any file you should have at least:

A descriptive title for the program, function(s), or class(es) in the file.
Your name and the date.
Dates and comments on subsequent changes. If the person making the modifications is not the original author, leave the original author's name but identify the name of the modifier with the documentation of the modification.

For each function in the file, you also include:

How the program or function should be called. For programs, this means command name and arguments; for functions, function signature and pre- and post-conditions.
What the program or function does (i.e., what problem it addresses).
A description of the method (the algorithm) used. This may have to be drawn out to be clear. It may allude to the variables or data structures used for the different sections of the algorithm. (Implementation files only)
A description of the input and output to be expected (including any assumptions about I/O format). In the case of functions, this should include the formal parameters, return values, I/O, and any global variables used.

If the file contains only a single function, this information should be in the header. Otherwise, it should be immediately above each function implementation.

The following templates may be used as a starting point for your documentation.

It is strongly recommended that you use the format for comments shown in these templates. We have also provided sample header documentation for a function to calculate averages. This example is based on the first template.

Variable Declaration Comments

In the declaration section, provide a short description of the logical role played by each variable. Organize this section as a legend. For example, in a C++ program you might have:

    double weight;       // The package's weight in kilograms

Comments for Code Sections

Each section that performs a task should be preceded by a comment explaining the purpose of the section and the algorithm being used to carry it out. Individual statements that are complex or non-intuitive should also be preceded by comments (or followed by a comment if it fits on the same line). An end brace after a long block should have a short comment connecting it to its respective beginning brace. You should also include such comments for end braces when you have a number of nested blocks. Here is an example in C++:

    // CALCULATE THE AVERAGE by summing the values and
    // then dividing by the number of values.
    sum = 0;
    for ( i = 0; i <  max; i++ )
    {
        sum = sum + values[i];      // accumulate sum
        // other statements if necessary ...
    } // end of loop calculating sum
    avg = sum / max;

Use blank lines to separate different sections of the program (see the Program Style Guide).