CS Department
Documentation Standards (Java Version)

Last revised: January 2003

Synopsis

The following is a description of expected program documentation. See also the Program Style Guide and the Java class template and main class template.

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 ...
Documenting methods ...
Documenting variables ...
Commenting code sections ...

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 modifer as such.

You should also include class documentation comments immediately preceding the class definition. The class documentation comments should include:

brief synopsis (one sentence)
detailed description
example code segment using the class
author list using the JavaDoc @author tag

Note that because of a "feature" in JavaDoc, you must precede all example code with an asterisk on each line to preserve your indenting.

The following format for the comments at the beginning of a file containing a class definition is recommended:

   /*  IntVector Class (Dynamic Array of Ints)
    *  Author: KC Student
    *      with assistance from: Lab Partner and Teaching Assistant
    *  Creation Date: 9/15/03
    *      Modified:    9/15/03   KC Student and PP Partner
    *                   Changed implementation of append()
    */

   /** A vector class optimized for working with ints. 
    *
    *  Like the Vector object, except rather than tracking a dynamic
    *  array of pointers to different objects, this is simply a
    *  dynamic array of ints.  The advantage is speed and memory
    *  savings.
    *  <p>
    *  Example:
    *     <pre>
    *      
    *                 // example here
          </pre>
    *  @author KC Student
    *  @author PP Partner
    */
   public class IntVector
   {
       ...
   }

Method Comments

The documentation comments for methods should include:

brief synopsis (one sentence)
detailed description (if necessary)
parameter list using the @param tag for each parameter (if there are any parameters)
return value using the @return tag (if anything is returned)
exception list using the @exception tag (if there are any exceptions thrown)

This information should be immediately above each method definition. Here is an example:

    /** Determine whether the given coordinates specify a valid
     *      location.
     *  @param      x    the x coordinate to be checked
     *  @param      y    the y coordinate to be checked
     *  @return     true if the specified location is within bounds
     */
    public boolean validLoc(int xCoord, int yCoord)
    {
        ...
    }

Commenting Variables

As you define variables, whether instance or class variables, or local variables within a method, provide a short description of the logical role played by the variable if the name is not enough to make this obvious. For example, you might have:

double weight = 0.0; // package's weight in kilograms
Address destination; // address to which package should be sent

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 Java:

    // 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).

CS Department Documentation Standards (Java Version)