[jdom-interest] Re: Exception documentation

[Joseph Bowbeer]

Hallvard Trætteberg writes:

> the question Elliotte raises is whether the throws clause
> should indicate which subclass of JDOMException that
> is actually raised, instead of the general JDOMException

Oh.  Then I like that suggestion, too.

When Elliotte used the term "runtime exception" I thought he was referring
to exceptions derived from RuntimeException, which are unchecked.

We may need to think about this again in the context of the spec.  For
example, are there some cases where we would specify a blanket
"JDOMException" but use specific JDOMException subclasses in the reference
implementation?


----- Original Message -----
From: "Hallvard Trætteberg" <hal at idi.ntnu.no>
To: "Joseph Bowbeer" <jozart at csi.com>
Sent: Tuesday, April 30, 2002 1:53 AM
Subject: RE: [jdom-interest] Re: Exception documentation

Joseph,

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

But this is concerned with "Unchecked exceptions", not JDOMExceptions that
this discussion is about. As far as I understand, the question Elliotte
raises is whether the throws clause should indicate which subclass of
JDOMException that is actually raised, instead of the general JDOMException.

Hallvard

> --- 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?
>