commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luc Maisonobe <Luc.Maison...@free.fr>
Subject Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random: RandomData.java RandomDataImpl.java
Date Sat, 14 Jan 2012 13:24:08 GMT
Hi Gilles,

Le 13/01/2012 11:59, Gilles Sadowski a écrit :
> On Fri, Jan 13, 2012 at 07:04:10AM -0000, celestin@apache.org wrote:
>> Author: celestin
>> Date: Fri Jan 13 07:04:10 2012
>> New Revision: 1230906
>>
>> URL: http://svn.apache.org/viewvc?rev=1230906&view=rev
>> Log:
>> Javadoc
>> Made sure that exceptions are documented in both javadoc and method signatures.
> 
> This is not good style: Unchecked exceptions in method signatures do not
> offer any guarantee to the caller;

This is still better than nothing. Not giving any hints to user about
exceptions that may be thrown is even worse style IMHO.

> not that only those exceptions will be
> thrown and not even that these exceptions can actually be thrown.
> Thus, it brings a level of redundancy (between Javadoc and signatures) that
> must be kept in sync manually; this is a burden and has no benefit.[1]
> Unchecked exceptions must be documented in Javadoc, but should not appear in
> method signatures (at least, not systematically).
> 
> 
> Best regards,
> Gilles
> 
> [1] Luc likes to have the exception in the signatures because, as a CM
>     developer, he can (temporarily) change the definition of an exception
>     (to make it "checked") and then the compiler will tell whether some
>     (user) code is prepared to handle that exception. But who else is going
>     to do that?

I used to do that when we still had a single root hierarchy. Changing
the root temporarily to checked was a simple and efficient way to make
sure javadoc was OK.
Now we have removed the single root and this has become a nightmare to
maintain as every single exception has to be temporarily changed to
checked in order to do this bookkeeping. This is impossible to do.

As Throwable, Exception and RuntimeException are all classes and not
interfaces, we can even not declare some intermediate MathThrowable
interface that would extend RuntimeException in production distribution
and could be changed to extend Exception in developers works spaces to
ensure javadoc and throws statements are up to date. I sincerely regret
this.

Luc


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


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


Mime
View raw message