commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Craig R. McClanahan" <craig...@apache.org>
Subject Re: [math] @throws IllegalArgumentException
Date Tue, 17 Jun 2003 06:09:30 GMT


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.

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.

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


Mime
View raw message