[jdom-interest] Re: Exception documentation

[Joseph Bowbeer]

Elliotte Rusty Harold writes:

> 1. All methods that throw a JDOM-specific runtime exception
> such as IllegalNameException should include an @throws
> comment for that exception.
>
> 2. All methods that throw a JDOM-specific runtime exception
> such as IllegalNameException should include that exception
> in their throws clause, even though the Java compiler does
> not require this.


I like #1 but not #2, and I'm not alone :-)

Item 44 in Effective Java says:

"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."

How to Write Doc Comments goes so far as to say:

"It is considered poor programming practice to include unchecked exceptions
in the throws clause."

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#throwstag

I've never read a good explanation why not, but this guideline suits me just
fine.  It places a clear guideline on the method signature while leaving
room for editorializing in the javadoc.


--- original message ---

From: Elliotte Rusty Harold <elharo at metalab.unc.edu>
To: jdom-interest <jdom-interest at jdom.org>
Subject: [jdom-interest] Exception documentation

We've been inconsistent about reporting runtime exceptions like
IllegalNameException in both method signatures and JavaDoc comments. For
example, in the Element class the setName() method is declared like so:

     * @throws IllegalNameException if the given name is illegal as an
     *         Element name.
     */
    public Element setName(String name) {


However, the public constructors that all call setName() do not include
an @throws clause for the same exception. Similar issues occur
throughtout the JDOM packages.

I'd like to propose the following coding conventions:

1. All methods that throw a JDOM-specific runtime exception such as
IllegalNameException should include an @throws comment for that exception.

2. All methods that throw a JDOM-specific runtime exception such as
IllegalNameException should include that exception in their throws
clause, even though the Java compiler does not require this.

I think this will make the JavaDoc and the code more completely
descriptive. It should have absolutely no effect on the actual behavior
of the classes and should not in any way break anybody's exisitng code.
Thoughts? Comments?