Standards for documentation comments.
GJSG 7 Javadoc is normative, with the amendments below.
GJSC 7.3.1 Exception: self-explanatory methods:
Javadoc is optional for “simple, obvious” methods like
getFoo, in cases where there really and truly is nothing else worthwhile to say but “Returns the foo”.Important: it is not appropriate to cite this exception to justify omitting relevant information that a typical reader might need to know. For example, for a method named
getCanonicalName, don’t omit its documentation (with the rationale that it would say only/** Returns the canonical name. */) if a typical reader may have no idea what the term “canonical name” means!
While we do not contradict this entirely, we qualify it:
Omitting the Javadoc comment entirely, even for a “self-explanatory” method, should be treated as a truly exceptional condition. In most cases, there should be some comment, even if just a summary fragment.
Remember: Your documentation is likely to be read in an HTML page, without the reader having access to the implementation details of your class. Thus, a comment like
/** Returns age. */
may well be meaningless or of little value, especially if age is a private field.
However, the comment
/** Returns the age (in generations) of this cell. */
is potentially much more meaningful, doesn’t depend on the reader knowing anything about the existence of an age field, and shouldn’t be omitted.
A Javadoc comment may be omitted for a @param or @return tag, when such a comment would simply repeat what is already stated in the method-level Javadoc comment. This is most often the case for an accessor or mutator (getter or setter) method, where a comment fragment for the @return or @param tag (respectively) would tend to repeat the summary fragment of the method itself.
On the other hand, the reverse of the above exception is not permitted: The method-level Javadoc comment must not be omitted if a comment is provided for a @param, @return, or @throws tag of the same method. In other words, if a method includes any Javadoc comments at all, it must include at least the summary fragment comment for the method itself.