On Sat, 14 Jun 2003, David Graham wrote:
> Date: Sat, 14 Jun 2003 17:02:35 -0600 > From: David Graham <[EMAIL PROTECTED]> > Reply-To: Jakarta Commons Developers List <[EMAIL PROTECTED]> > To: [EMAIL PROTECTED] > 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
