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
java.io.DataInputStream#readByte(), there are both IOException and
EOFException documented. EOFException is a subclass of IOException. As
you know a normal InputStream.read() 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]: <http://www.amazon.com/dp/0321356683/>
--
e-mail: [email protected]
web: www.alexanderkiel.net
signature.asc
Description: This is a digitally signed message part
