Hi Jeremias, > Makes sense. I stumbled over that myself from time to time but it didn't > really bother me so much to take action.
Okay. Can you please modify the checkstyle XML files to reflect that? I'm a great fan of that checkstyle stuff. I didn't use it before, but I find a common coding style important for such a big and shared project like FOP. What's about severities? Did you commit code with checkstyle errors? Best Regards Alex > 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 > > 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 > > > > > > > Jeremias Maerki > >
signature.asc
Description: This is a digitally signed message part
