Java Reference
In-Depth Information
bracketed with
/
** and *
/
. End-of-line comments are preceded with
//
and
extend to the end of the line. Table 9.4, and the program that follows,
describes the comment classes with examples.
Table 9.4
Java has three comment styles.
Comment Style Name
Example of Comment Style
Usage of Comment Style
Documentation comments
/**
* ClassName
* @author: Bruce Tate
*/
Use for comments that are use-
ful in code, and in automati-
cally generated documentation
(JavaDoc).
Block, or C-style comments
/* step 1
* step 2
* step 3
*/
Use to block a piece of code
from executing, or to document
a long description or algorithm.
End-of-line, or single-line
comments
i = 1; // a comment
Use to drop in annotations at
the end of a line, or to drop in
short comments between lines.
/**
* CommentClass: This class shows the three types of comments.
* @Author: Bruce A. Tate
*
*/
public class CommentClass {
int someVariable; // This variable serves no purpose.
/*
imp anotherVariable; // Why won't this work?
*/
}
Documentation comments are processed by the JavaDoc utility, which pro-
duces documentation from tags in the comments. We use end-of-line com-
ments to document variables and individual lines of programs. We use block
style comments to block out segments of code from execution for testing pur-
poses, or to provide algorithm type comments in the middle of a member
function.
Block style comments can also be bug prone, and they can interfere with
the placement of block comments for debugging purposes. They should not
be used mid-line or for smaller sections. In my opinion, the unclosed com-
ment is a particularly insidious bug that can be very difficult to track, espe-
cially in distributed code. This is another case where a good editor is worth its
weight in gold. Bugs like this one, and the related bug of matching closing
