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
Search WWH ::




Custom Search