commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <stei...@yahoo.com>
Subject Re: [math] @throws IllegalArgumentException
Date Tue, 17 Jun 2003 06:48:03 GMT

--- "Craig R. McClanahan" <craigmcc@apache.org> wrote:
> 
> 
> On Sat, 14 Jun 2003, David Graham wrote:
> 
> > Date: Sat, 14 Jun 2003 17:02:35 -0600
> > From: David Graham <dgraham1980@hotmail.com>
> > Reply-To: Jakarta Commons Developers List <commons-dev@jakarta.apache.org>
> > To: commons-dev@jakarta.apache.org
> > Subject: Re: [math] @throws IllegalArgumentException
> >
> > >I am dutifully cleaning up the CheckStyle warnings in my code and I am
> > >hesitating to remove @throws IllegalArgumentException, which CheckStyle
> > >currently complains about. I am a little ambivalent about this.  There is
> a
> > >property (checkstyle.javadoc.checkUnusedThrows) that we can set to make it
> > >ignore these. I notice that [lang] has this set to false. I actually
> prefer
> > >to leave these "unused throws tags" in. Any strong opinions on this?
> >
> > There are many Java classes that use the @throws tag with a
> > RuntimeException.  Removing it from the javadoc is a very bad idea because
> > it always helps to know what exceptions a method throws.  I'm assuming
> > checkstyle is complaining because the exception isn't listed in the actual
> > throws signature which is easily fixable.
> >
> 
> My personal opinion is that it's entirely reasonable to Javadoc-document
> RuntimeException exceptions that might be thrown, even if they are not
> included in the "throws" clause on the method itself.  The entire reason
> for making the actual exception a RuntimeException is so that an
> application calling the method casually will not have to worry about
> try/catch blocks -- but advanced users will DEFINITELY appreciate the
> hints about what kinds of checks the method is actually performing.
> 
I agree. In general, we are calling out the boundary/exception generating
conditions in the body of the javadoc comments; but I would like to add the
tags as well.  The only way I can make checkstyle happy when doing this is to
add the throws clauses as David suggests.

> Therefore, it also seems reasonable to me that CheckStyle should support a
> mode where it still complains about Javadoc'd exceptions no listed in the
> "throws"  clause -- but ONLY if those exceptions are not
> RuntimeExceptions.

I agree. 

> 
> FWIW, the JavaServer Faces spec (for which I'm co-spec-lead) is trying to
> be pretty rigorous about documenting where some typical runtime exceptions
> might be thrown -- particularly things like NullPointerException on null
> arguments that should really be non-null -- with the goal of improving the
> predicatability of various implementations of JavaServer Faces.  I'd be
> *really* unhappy with CheckStyle if it complained about all of the
> explicit JavaDoc declarations (which it sounds like it will right now).
> 
> > David
> >
> 
> Craig
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 


__________________________________
Do you Yahoo!?
SBC Yahoo! DSL - Now only $29.95 per month!
http://sbc.yahoo.com

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message