Java Reference
In-Depth Information
. . .
}
Your first reaction may well be ȒWhoa! Am I supposed to write all this stuff?ȓ These
comments do seem pretty repetitive. But you should take the time to write them, even
if it feels silly.
It is always a good idea to write the method comment first, before writing the code in
the method body. This is an excellent test to see that you firmly understand what you
need to program. If you can't explain what a class or method does, you aren't ready to
implement it.
What about very simple methods? You can easily spend more time pondering
whether a comment is too trivial to write than it takes to write it. In practical
programming, very simple methods are rare. It is harmless to have a trivial method
overcommented, whereas a complicated method without any comment can cause real
grief to future maintenance programmers. According to the standard Java
documentation style, every class, every method, every parameter, and every return
value should have a comment.
Provide documentation comments for every class, every method, every parameter,
and every return value.
The
javadoc
utility formats your comments into a neat set of documents that you
can view in a web browser. It makes good use of the seemingly repetitive phrases.
The first sentence of the comment is used for a summary table of all methods of your
class (see
Figure 3
). The
@param
and
@return
comments are neatly formatted in
the detail description of each method (see
Figure 4
). If you omit any of the comments,
then
javadoc
generates documents that look strangely empty.
This documentation format should look familiar. The programmers who implement
the Java library use
javadoc
themselves. They too document every class, every
method, every parameter, and every return value, and then use
javadoc
to extract
the documentation in HTML format.
91