@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 :
throws
clause is a widely followed convention
throws
clause
throws
clause.
@param
tag.
@throws
at all
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 manufacturer non-null and has visible content. * @param diameter in centimeters, in the range 1..50. * @throws IllegalArgumentException if diameter not in given range. * @throws IllegalArgumentException if manufacturer has no visible content. * @throws NullPointerException if manufacturer is null. */ BasketBall(String manufacturer, int diameter){ //..elided } /** * @param diameter in centimeters, in the range 1..50. */ BasketBall(int diameter){ //..elided } // PRIVATE private String manufacturer; private int diameter; }