On 27.09.2009 13:27:35 Alexander Kiel wrote: > 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?
Sure, but only after a period of at least 72 hours to allow the other committers to raise an objection. > 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? No, I always fix errors (mine or others'). Sometimes tab characters creep in, for example. The Checkstyle plug-in for Eclipse is really helpful in that department. If I didn't fix Checkstyle errors I might not notice any build failures prior to a commit. > 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 > > > > > Jeremias Maerki
