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.

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.

	  // 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;
	

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.

	    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;
	  

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;
  }
}