Avoid @throws in javadoc

Some argue that @throws should not be used at all. Instead, one may simply rely on the javadoc tool to automatically document all exceptions placed in the throws clause. However, others disagree.

Checked Exceptions :

Unchecked Exceptions : Therefore, if you : then only checked exceptions will appear in javadoc. It can be argued that this is beneficial: since checked exceptions are more important than unchecked ones, it's best that they stand out in javadoc, without being mixed in with other exceptions of minor interest.

In almost all cases, a @throws tag simply repeats verbatim conditions already stated in a @param tag, and doesn't add in any way to the specification of the method's behavior. Such repetition should be regarded with grave suspicion. When a change occurs, it's far too easy to forget to update the javadoc in two separate places.

A general comment regarding broken contracts can be stated once in the javadoc overview.html document :
"If the requirements or promises of any method's contract are not fulfilled (that is, if there is a bug in either the method or its caller), then an unchecked exception will be thrown. The precise type of such an unchecked exception does not form part of any method's contract."

Example

BasketBall has two constructors.

The first constructor includes several @throws tags in its javadoc. However, aside from the type of the unchecked exception, all of these @throws tags are logically equivalent to some previous statement in a @param tag. They add nothing to the contract.

The second constructor follows a different style. It has a single parameter, and the conditions on this parameter are stated once (and once only) in its @param tag.


public final class BasketBall {

  /**
  * @param aManufacturer non-null and has visible content.
  * @param aDiameter in centimeters, in the range 1..50.
  * @throws IllegalArgumentException if aDiameter not in given range.
  * @throws IllegalArgumentException if aManufacturer has no visible content.
  * @throws NullPointerException if aManufacturer is null.
  */
  BasketBall(String aManufacturer, int aDiameter){
    //..elided
  }

  /**
  * @param aDiameter in centimeters, in the range 1..50.
  */
  BasketBall(int aDiameter){
    //..elided
  }

  // PRIVATE
  private String fManufacturer;
  private int fDiameter;
} 



See Also :
Javadoc all exceptions
Design by Contract
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 -