2. Commenting Conventions

Comments provide readers with the information helpful for understanding your program.

Use comments to provide overviews or summaries of chunks of code and to provide additional information that is not readily available in the code itself.

Comment the details of nontrivial or nonobvious design decisions; avoid comments that merely duplicate information that is present in and clear from reading the code. We will use three types of comments:

In addition, the C style comments /* … */ may be used temporarily for commenting out blocks of code during debugging. Programs submitted for a grade should not have blocks of code commented out however. Either fix the code or remove it from the program.

For readability, always leave space around the comment delimiters, and format multi-line comments nicely.

Always comment your code in English. See the Naming Conventions for why.

2.1. File Header Comments

File header comments provide information pertaining to the file as a whole. This includes at least the date of creation, the name of the creator, and a brief description of the code contained therein.

In real life, file header comments also contain revision and copyright information.

2.2. Single-Line Comments

Use single-line comments to provide brief summary comments for chunks of code.

Precede single-line comments with a blank line and align the comment with the code it summarizes. Do not feel the need to comment every single line of code, rather summarize chunks of code between 3 to 7 lines in length.

In Java and C++, begin single-line comments with a double slash (//) that tells the compiler to ignore the rest of the line.

2.2.1. Rationale

By separating chunks of code by blank lines and preceding each chuck with an explanatory comment, readers (and yourself) can quickly identify and understand sections of code where specific actions are being performed.

Why limit such comments to one line? Well, there is no absolute limit. However, if you think you need more than one or two lines to document a piece of code, you should ask yourself if that comment should not rather go into the method or function header. Lengthy explanations are typically relevant to the user of a function (e.g., details of a search algorithm, numerical methods used), and as such belong into the function documentation.

Always add comments while you are coding rather than waiting until the program is finished. The summaries and reasons will be fresh and accurate rather than place-fillers that offer no real value.

	  // Compute the exam average score for the midterm exam
	  int sumOfScores = 0;
	  for (int i = 0; i < scores.length; i++)
	    sumOfScores = sumOfScores + scores[i];
	  average = float(sumOfScores) / scores.length;

2.3. Trailing Comments

Trailing comments are used to provide an explanation for a single line of code. Begin trailing comments with a double slash (//) and place them to the right of the line of code they reference.

Trailing comments are used to explain tricky code, specify what abbreviated variable names refer to, or otherwise clarify unclear lines of code.

In general, see whether trailing comments are really necessary, or whether you can rewrite tricky or unclear code, use meaningful variable names, or otherwise enhance the self-documenting character of the code.

2.3.1. Rationale

Trailing comments are a throwback to the days of assembly language programming where single lines of code were impossible to understand without the use of comments.

Modern programming languages like Java allow programmers to write self-documenting code using meaningful variable names, eliminating the need for trailing comments in many cases.

Compare the following two pieces of code:

	    ss = s1 + s2 + s3; // add the three scores into the sum
	    a = float(ss) / 3; // calculate the mean of the scores

	    sumOfScores = score1 + score2 + score3;
	    meanScore = float(sumOfScores) / NUM_SCORES;

The second version is more readable even though there are no comments.

2.4. Documentation of Classes and Methods

Comments are not sufficent to provide a complete documentation of your program. In addition, every class and method need to have a description of its behaviour and usage. For Java, the Sun JavaDoc standard is a powerful technique to write comments and allows the programmer to automaticaly generate the html documentation. For C++ and C, Doxygen is a powerful and elegant system for source documentation using the same philosophy and syntax.

Use JavaDoc or Doxygen to document your code.

Here is an example of a method documentation:

 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
public Image getImage(URL url, String name) {
  try {
    return getImage(new URL(url, name));
  } catch (MalformedURLException e) {
    return null;