Last revised: January 2003
Documentation Standards (Java Version)
The following is a description of expected program documentation. See also
the Program Style Guide and the Java
class template and
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
What comments should always be in a program?
At the beginning of any
you should have at least:
You should also include class documentation comments
the class definition. The class documentation comments should include:
A descriptive title for the program, function(s), or class(es) in
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.
Note that because of a "feature" in JavaDoc, you must precede all example
code with an asterisk on each line to preserve your indenting.
brief synopsis (one sentence)
example code segment using the class
author list using the JavaDoc @author tag
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
* // example here
* @author KC Student
* @author PP Partner
public class IntVector
The documentation comments for methods should include:
This information should be immediately above each method definition.
Here is an example:
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
(if there are any exceptions thrown)
/** Determine whether the given coordinates specify a valid
* @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)
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).