[jdom-interest] Re: Exception documentation

[Bart Read]

Yeah, I agree with Joseph here.  Unchecked exceptions should not appear in
the throws clause but should appear in the Javadoc.
Bart


----- Original Message -----
From: "Joseph Bowbeer" <jozart at csi.com>
To: <jdom-interest at jdom.org>
Cc: <elharo at metalab.unc.edu>
Sent: Tuesday, April 30, 2002 9:11 AM
Subject: [jdom-interest] Re: Exception documentation


> 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?
>
>
>
> _______________________________________________
> To control your jdom-interest membership:
>
http://lists.denveronline.net/mailman/options/jdom-interest/youraddr@yourhos
t.com
>
> ---------- Automatically inserted by WDI Mailserver ----------------
> This message has been scanned for virus, trojans, illegal relays and
> spam. If you have any comments, problems or questions please do not
> hesitate to contact:
> Abbotsbury Software Ltd
> Tel: +44 1305 871543 Fax: +44 1305 871688
> Email: postmaster at wdi.co.uk
> Web: http://www.wdi.co.uk/virus.phtml