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 (
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:
@author name-- The name of the person who programmed this class
@version version-- The version number or date of the program
@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
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
can figure out for itself. For example, don't mention the type of a parameter
@param tag--if you later change its type, you may forget to
change your comment, but
javadoc will never get it wrong.