Java Practices -> Use javadoc liberally

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.

Oracle has published this style guide for writing javadoc comments.

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.

Javadoc 1.4 has added many features, including:

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)

Javadoc 1.5 has these notable additions :

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

The package-info.java file is unusual since it doesn't contain a class. Indeed, the name package-info is not a valid class name. Here is a simple example of its contents:

/** 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;