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:

If javadoc is written correctly, then:

Oracle has published this style guide for writing javadoc comments.

Note that:

Javadoc 1.4 has added many features, including: Javadoc 1.5 has these notable additions :

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:

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;


See Also :
Document thread safety
Construct classes from the outside in
Design by Contract
Avoid basic style errors
Would you use this technique?
Yes   No   Undecided   
© 2014 Hirondelle Systems | Source Code | Contact | License | RSS
Individual code snippets can be used under this BSD license - Last updated on September 21, 2013.
Over 2,000,000 unique IPs last year - Built with WEB4J.
- In Memoriam : Bill Dirani -