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
> 
> 

Attachment: signature.asc
Description: This is a digitally signed message part

Reply via email to