Comments

A comment is text intended for the human reader of a program. It is ignored by the compiler.

There are three kinds of comments in Java:

A comment can begin with two slashes (//) and continue to the end of the line. This kind of comment is called either a single-line or end-of-line comment. The single-line comment is on a line by itself, and says something about the line or lines of code that follow it; the end-of-line comment is placed on the same line as a statement or declaration, and says something about that statement or declaration. For example,

// Apply the Pythagorean theorem (single-line comment)
x = 3.0;
y = 4.0;
z = Math.sqrt(x * x + y * y); // Compute hypotenuse (end-of-line comment)

This kind of comment is also used to "comment out" code that the programmer wants to keep in the program, but wants to disable temporarily. For example,

// System.out.println("New value of z = " + z);

A multiline comment starts with slash-asterisk (/*) and ends with asterisk-slash (*/). Line boundaries don't matter. Multiline comments are not used very much in Java; they are sometimes used to explain some unusual implementation method.

A Javadoc comment starts with slash-asterisk-asterisk (/**) and ends with asterisk-slash (*/). Javadoc comments provide user-level documentation for classes, methods, and variables. The Java API is created using Javadoc comments.

A Javadoc comment must immediately precede the declaration of the class, interface, variable, or method that is being described. In any other location it will be ignored (and will look like a mistake).

Javadoc comments may contain various tags. The most common tags are:

• Within a Javadoc comment for a class or interface:
  • @author name -- The name of the person who programmed this class
  • @version version -- The version number or date of the program
    
• Within a Javadoc comment for a method:
  • @param name purpose -- Describes what information is being given to the method in the named parameter
  • @return result -- Describes the result that can be expected from the method
  • @throws exception -- Describes why the named exception might be thrown by the method

Javadoc comments are processed by a special utility, named javadoc, that reads the program and produces documentation in the form of professional-level HTML pages. Even if you don't put Javadoc comments in your program, javadoc can create good documentation that lists the methods and parameters in a class.

Javadoc comments are used almost exclusively by other programmers who want to use your classes and methods. They care about what your code does, not how you did it. Javadoc comments should be written with this in mind.

You should avoid putting anything in your Javadoc comments that javadoc can figure out for itself. For example, don't mention the type of a parameter in a @param tag--if you later change its type, you may forget to change your comment, but javadoc will never get it wrong.