[jdom-interest] Re: Exception documentation

[Elliotte Rusty Harold]

At 1:11 AM -0700 4/30/02, Joseph Bowbeer wrote:


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

I disagree with this document on this point. I think it does help to 
include them in the throws clauses. I'll also note that the document 
also states:

Note that the Java Language Specification also shows unchecked 
exceptions in throws clauses (as follows). Using the throws clause 
for unchecked exceptions in the spec is merely a device meant to 
indicate this exception is part of the contract between the caller 
and implementor. The following is an example of this (where "final" 
and "synchronization" are removed to make the comparison simpler).

java.util.Vector source code:


     public Object elementAt(int index)

java.util.Vector spec in the Java Language Specification, 1st Ed. (p. 656):


     public Object elementAt(int index) throws IndexOutOfBoundsException

However, in our case we don't have separate documentation for the 
methods aside from the source code. Thus it's appropriate for us to 
include the unchecked exceptions we throw in the throws clause.
-- 

+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo at metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+
|          The XML Bible, 2nd Edition (Hungry Minds, 2001)           |
|             http://www.cafeconleche.org/books/bible2/              |
|   http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/   |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:  http://www.cafeaulait.org/      |
|  Read Cafe con Leche for XML News: http://www.cafeconleche.org/    |
+----------------------------------+---------------------------------+