Alex, The checkstyle checks are historically grown, and are therefore incomplete. I personally would turn on much more checks for certain style issues I like. IMO every option set helps deciding a certain factor. So more the more checks the better :)
(in short: +1 to your changes). Right now we have 3 checkstyle files: 3.5, 4.0, and 5.0, which also means the checks would need to be added in all of them (if possible). Can we remove any of them? I'd volunteer to modify the ant buildfile to support 5.0. I'd also vote for dropping 3.5 support, and potentially dropping checkstyle 4. Max 2009/9/26 Alexander Kiel <alexanderk...@gmx.net>: > 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: alexanderk...@gmx.net > web: www.alexanderkiel.net > >
