Use javadoc liberally
Javadoc is a great tool, and should be used with feelings of unbridled joy ;).
A method header combined with its associated javadoc form the specification, or contract, of a method. If the caller fulfills the stated requirements, then the method undertakes to fulfill its stated promises.
Using Javadoc acknowledges that there are two distinct questions a reader can ask about code:
- what is this supposed to do? (answered only by the javadoc and method header)
- how does it try to do it? (answered only by the implementation)
If javadoc is written correctly, then:
- one can understand exactly what services are offered by a method ("what is this supposed this do?"), without having to look at its implementation ("how does it try to do it?"). Reading an implementation usually takes a lot more effort than reading javdoc.
- the implementation can be checked for correctness versus the specification. That is, some bugs can be found just by reading the code, as opposed to executing it.
Note that:
- if you wish to provide high level descriptions, then you may use the file names overview.html (a conventional name) and package-info.java to do so (see below).
- javadoc is "inherited" - javadoc written for an interface method or an abstract method is automatically associated with corresponding concrete implementations
- it's a common error to put the class level javadoc comment at the very start of a source file, before the import statements. This is an error, since it must appear just above the class header.
- the -tag option allows user-defined custom tags. This feature can be used to implement common items such as @to.do, @is.Mutable, or @no.Nulls. (Oracle recommends placing a period somewhere in the custom tag, to avoid potential future conflicts with tags defined by Oracle.)
- the -linksource option generates an HTML version of your source code, and links the javadoc to the source. (The source is presented without any syntax highlighting, but this remains a very nice feature.)
- there is finer-grained control over how javadoc is inherited. The {@inheritDoc} tag is useful here (warning: this is broken in JDK 1.4.0)
- support for new language features, such as generics and annotations
- the @literal and @code tags for ensuring text is not treated as markup
Example:
/* * This comment is NOT a class level javadoc comment. * Such comments appear just above the class declaration, not at the * start of the file. */ import java.math.BigDecimal; /** * Guitar Model Object. * * <P>Various attributes of guitars, and related behaviour. * * <P>Note that {@link BigDecimal} is used to model the price - not double or float. * See {@link #Guitar(String, BigDecimal, Integer)} for more information. * * @author Les Paul * @version 2.0 */ final class Guitar { /** * Constructor. * * @param aName (required) brand name of the guitar. Must have content. Length * must be in range <tt>1..50</tt>. * @param aPrice (optional) purchase price of the guitar. * @param aNumStrings (required) number of strings on the guitar. Can take * values 6 or 12. */ Guitar(String aName, BigDecimal aPrice, Integer aNumStrings){ //...elided } //There is a one-line form of javadoc comment, useful for shorter text : /** Return name passed to the constructor. */ String getName(){ return null; } /** Return price passed to the constructor. */ BigDecimal getPrice(){ return null; } /** Value - {@value}, key for storing the current guitar of interest in the session.*/ public static final String KEY = "guitar"; /** * Play the guitar. * * This method makes no guarantees as to how <em>well</em> the song is played. * @param aSongTitle must have content, and must have trimmed length greater than 2. */ void play(String aSongTitle){ //..elided } /** * Apply standard tuning to the guitar. * * @return <tt>true</tt> only if the guitar has been properly tuned. */ boolean tune(){ return true; } /** * Destroy the guitar while on stage. * * @deprecated Not good for the environment. */ void lightOnFireAndSmashLikeAWildman(){ //..elided } //...other methods elided }
Prefer package-info.java to package.html
Originally, an HTML file named package.html was used to specify package level comments. That style is still available, but it's likely better to use package-info.java instead:
- it's shorter, since no boilerplate HTML is needed
- the leading '*' on each line can be discarded, making it easy to paste in existing HTML
- package-info.java is the only place to annotate a package, if needed
/** Edit the roles attached to a user. */ package hirondelle.fish.access.role;Here is an example including an annotation for the package:
/** Edit the settings attached to a user. */ @Unpublished package hirondelle.fish.access.user;Here is a final example without the leading '*' on every line:
/** Maintain a list of Members in the Fish and Chips Club. An Active Member will be part of the RSVP list. When a Member is inactive, they will not appear on the RSVP listing. @author B. P. Hennessey @version 1.0 */ package hirondelle.fish.main.member;
See Also :
Document thread safety
Construct classes from the outside in
Design by Contract
Avoid basic style errors
Construct classes from the outside in
Design by Contract
Avoid basic style errors
Would you use this technique?