[jdom-interest] RE: Exception documentation

Joseph Bowbeer jozart at csi.com
Tue Apr 30 11:46:51 PDT 2002

First, a point of clarification:

JDOMException is a checked exception, so no of this discussion applies to
JDOMException and its ilk.

This discussion applies only to the IllegalAdd/Data/Name/TargetException,
which derive from IllegalArgumentException (unchecked).

How to Write Doc Comments says:

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

Elliotte writes:

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

Isn't How to Write Doc Comments explaining why JLS documents the methods in
this way despite the fact that it is considered poor practice in actual

The way I see it is: because we have javadoc, there's no need for us to add
these to our code.  As a programmer, I expect to see checked exceptions in
the method signatures and if I want to learn about possible unchecked
exceptions I'll look at the javadoc.  If we think it is important to add
these extra exceptions to the signatures, I suggest we make them checked

Joe Bowbeer

More information about the jdom-interest mailing list