Item 62: Document all exceptions thrown by each method

1.  Always declare checked exceptions individually, and document precisely the conditions under which each one is thrown using the Javadoc @throws tag.

 

2.  Don’t take the shortcut of declaring that a method throws some superclass of multiple exception classes that it can throw.

 

3.  While the language does not require programmers to declare the unchecked exceptions that a method is capable of throwing, it is wise to document them as carefully as the checked exceptions. Familiarizing programmers with all of the errors they can make helps them avoid making these errors. A well-documented list of the unchecked exceptions that a method can throw effectively describes the preconditions for its successful execution. It is particularly important that methods in interfaces document the unchecked exceptions they may throw. This documentation forms a part of the interface’s general contract and enables common behavior among multiple implementations of the interface.

 

4.  Use the Javadoc @throws tag to document each unchecked exception that a method can throw, but do not use the throws keyword to include unchecked exceptions in the method declaration.

 

5.  If an exception is thrown by many methods in a class for the same reason, it is acceptable to document the exception in the class’s documentation comment rather than documenting it individually for each method. A common example is NullPointerException. It is fine for a class’s documentation comment to say, ”All methods in this class throw a NullPointerException if a null object reference is passed in any parameter” or words to that effect.