Makes sense. I stumbled over that myself from time to time but it didn't
really bother me so much to take action.

On 26.09.2009 14:41:37 Alexander Kiel wrote:
> Hi,
> why didn't our code style allow unchecked exceptions or subclasses of
> thrown exceptions in Javadoc?
> From checkstyle-5.0.xml:
> <module name="RedundantThrowsCheck">
>     <property name="allowSubclasses" value="false"/>
>     <property name="allowUnchecked" value="false"/>
>     <property name="severity" value="warning"/>
> </module>
> From "J. Bloch: Effective Java, Second Edition" [1] page 252:
> >Use the Javadoc @thows 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.
> Every good code I know, documents unchecked exceptions. Take the Java
> Collections API. Every possible ClassCastException or
> NullPointerException is documented.
> Another quote from J. Bloch:
> >A well-documented list of unchecked exceptions that a method
> >can throw effectively describes the preconditions for its
> >successful execution. It is essential that each method's
> >documentation describe its preconditions [...]
> I think that everyone can agree with the statements J. Bloch made. So I
> would strongly vote to allow documenting unchecked exceptions.
> The second point is not allowing subclasses of exceptions in Javadoc. I
> don't use this very often, but I have just one example in my mind where
> this makes sense. If you have a look into
>, there are both IOException and
> EOFException documented. EOFException is a subclass of IOException. As
> you know a normal returns -1 at EOF but readByte()
> doesn't. So it's worth documenting that readByte() is throwing a
> EOFException instead.
> So I would also vote allowing subclasses.
> Best Regards
> Alex
> [1]: <>
> -- 
> e-mail:
> web:

Jeremias Maerki

Reply via email to