commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From S├ębastien Brisard <sebastien.bris...@m4x.org>
Subject Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random: RandomData.java RandomDataImpl.java
Date Sun, 15 Jan 2012 12:13:34 GMT
Hi Gilles,
>>
>> An alternative would be to document unchecked exceptions in the
>> javadoc, but not in @throws tags. Something along the lines "this
>> method should throw/throws an XXXException if...". This way, we would
>> be able to remove the exceptions from the method signature if we feel
>> that it would be better, and checkstyle would not complain (although I
>> actually don't think it does with the current settings).
>> I do not have any preference, here. However, I do like the fact that
>> unchecked exceptions *are* somehow documented, just to remind me what
>> preconditions I should check (as a user).
>
> I don't understand why you suggest to not use "@throws" tags.
>
Because I thought you were not too happy with that. I obviously
misunderstood, sorry.

>
> All (non-trivial) exceptions must be documented. The Javadoc "@throws" is
> especially useful for advertising _unchecked_ exception.
> [In some sense, "@throws" tags are redundant for checked exceptions, because
> those are detected by the parser/compiler and their existence can be
> advertised automatically.]
>
> Checkstyle indeed does not complain if an unchecked exception is documented
> but does not appear in the signature of a method.
>
> I think that the rules stated in "Effective Java" are simple and consistent.
>
That's fine with me. Thanks again.
Best regards,
S├ębastien


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


Mime
View raw message