Java Programming Tip: Inserting Comments

A program can be documented by inserting comments at relevant places. These comments are for documentation purposes and are ignored by the compiler.

Java provides three types of comments to document a program:

A single-line comment: // … to the end of the line

A multiple-line comment: /* … */

A documentation (Javadoc) comment: /** … */

Single-line Comment
All characters after the comment-start sequence // through to the end of the line constitute a single-line comment.

// This comment ends at the end of this line.
int age;        // From comment-start sequence to the end of the line is a comment.

Multiple-line Comment
A multiple-line comment, as the name suggests, can span several lines. Such a comment starts with /* and ends with */.

/*  A comment
on several
lines.
*/

The comment-start sequences (//, /*, /**) are not treated differently from other characters when occurring within comments, and are thus ignored. This means trying to nest multiple-line comments will result in compile time error:

/*  Formula for alchemy.
gold = wizard.makeGold(stone);
/* But it only works on Sundays. */
*/

The second occurrence of the comment-start sequence /* is ignored. The last occurrence of the sequence */ in the code is now unmatched, resulting in a syntax error.

Documentation Comment
A documentation comment is a special-purpose comment that when placed before class or class member declarations can be extracted and used by the javadoc tool to generate HTML documentation for the program. Documentation comments are usually placed in front of classes, interfaces, methods and field definitions. Groups of special tags can be used inside a documentation comment to provide more specific information. Such a comment starts with /** and ends with */:

/**
*  This class implements a gizmo.
*  @author K.A.M.
*  @version 2.0
*/