You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles Sadowski <gi...@harfang.homelinux.org> on 2012/01/13 11:59:13 UTC
Re: svn commit: r1230906 - in
/commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
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; 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?
> [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: svn commit: r1230906 - in
/commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
On Sun, Jan 15, 2012 at 01:13:34PM +0100, Sébastien Brisard wrote:
> 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.
Glad we agree in fact. ;-)
> [...]
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Sébastien Brisard <se...@m4x.org>.
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
Re: svn commit: r1230906 - in
/commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hi Sébastien.
> thank you for taking part in this discussion.
> >
> > Hi Sébastien,
> >
> >>
> >>>
> >>> 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
> >>>
> >> what I did in r1230906 was
> >> 1. make sure that exceptions actually thrown in RandomDataImpl are
> >> identical with the @throws clause in the Javadoc of RandomData.
> >> 2. add the unchecked exceptions to the methods signatures.
> >
> > Good, thanks.
> >
> >>
> >>>From what I understand, all exceptions should remain in the javadoc,
> >> right?
> >
> > I think so, but it is only *my* opinion. For now, we let everybody do as
> > they want.
> >
> >> As for methods signatures, I should probably get rid of the
> >> throws in the interface RandomData. How about RandomDataImpl? Would
> >> you rather have the exceptions in the method signature, or not?
> >
> > I'm not sure either. People will look at the interface documentation, so
> > the javadoc here could notify about the exceptions if you feel inclined
> > to put them here. In all cases, it is better to have javadoc and throws
> > clause consistent (I think checkstyle may complain otherwise, depending
> > on its settings about checked/unchecked).
> >
> >>
> >> Thanks for your advice, and I promise I'll clean up my mess ASAP.
> >
> > Don't worry, you did not put any mess here. We (and especially I) put it
> > by ourselves ;-)
> >
> > Luc
> >
> So, are you both happy if I leave this commit "as is"?
>
> 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.
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.
Best,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Luc Maisonobe <Lu...@free.fr>.
Le 15/01/2012 10:26, Sébastien Brisard a écrit :
> Hello Luc and Gilles,
> thank you for taking part in this discussion.
>>
>> Hi Sébastien,
>>
>>>
>>>>
>>>> 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
>>>>
>>> what I did in r1230906 was
>>> 1. make sure that exceptions actually thrown in RandomDataImpl are
>>> identical with the @throws clause in the Javadoc of RandomData.
>>> 2. add the unchecked exceptions to the methods signatures.
>>
>> Good, thanks.
>>
>>>
>>> >From what I understand, all exceptions should remain in the javadoc,
>>> right?
>>
>> I think so, but it is only *my* opinion. For now, we let everybody do as
>> they want.
>>
>>> As for methods signatures, I should probably get rid of the
>>> throws in the interface RandomData. How about RandomDataImpl? Would
>>> you rather have the exceptions in the method signature, or not?
>>
>> I'm not sure either. People will look at the interface documentation, so
>> the javadoc here could notify about the exceptions if you feel inclined
>> to put them here. In all cases, it is better to have javadoc and throws
>> clause consistent (I think checkstyle may complain otherwise, depending
>> on its settings about checked/unchecked).
>>
>>>
>>> Thanks for your advice, and I promise I'll clean up my mess ASAP.
>>
>> Don't worry, you did not put any mess here. We (and especially I) put it
>> by ourselves ;-)
>>
>> Luc
>>
> So, are you both happy if I leave this commit "as is"?
Yes.
>
> 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).
If this is fine with you, then it is good for me.
Luc
> Sébastien
>
>
> ---------------------------------------------------------------------
> 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
Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Sébastien Brisard <se...@m4x.org>.
Hello Luc and Gilles,
thank you for taking part in this discussion.
>
> Hi Sébastien,
>
>>
>>>
>>> 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
>>>
>> what I did in r1230906 was
>> 1. make sure that exceptions actually thrown in RandomDataImpl are
>> identical with the @throws clause in the Javadoc of RandomData.
>> 2. add the unchecked exceptions to the methods signatures.
>
> Good, thanks.
>
>>
>>>From what I understand, all exceptions should remain in the javadoc,
>> right?
>
> I think so, but it is only *my* opinion. For now, we let everybody do as
> they want.
>
>> As for methods signatures, I should probably get rid of the
>> throws in the interface RandomData. How about RandomDataImpl? Would
>> you rather have the exceptions in the method signature, or not?
>
> I'm not sure either. People will look at the interface documentation, so
> the javadoc here could notify about the exceptions if you feel inclined
> to put them here. In all cases, it is better to have javadoc and throws
> clause consistent (I think checkstyle may complain otherwise, depending
> on its settings about checked/unchecked).
>
>>
>> Thanks for your advice, and I promise I'll clean up my mess ASAP.
>
> Don't worry, you did not put any mess here. We (and especially I) put it
> by ourselves ;-)
>
> Luc
>
So, are you both happy if I leave this commit "as is"?
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).
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Luc Maisonobe <Lu...@free.fr>.
Le 14/01/2012 17:50, Sébastien Brisard a écrit :
> Hello,
Hi Sébastien,
>
>>
>> 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
>>
> what I did in r1230906 was
> 1. make sure that exceptions actually thrown in RandomDataImpl are
> identical with the @throws clause in the Javadoc of RandomData.
> 2. add the unchecked exceptions to the methods signatures.
Good, thanks.
>
>>From what I understand, all exceptions should remain in the javadoc,
> right?
I think so, but it is only *my* opinion. For now, we let everybody do as
they want.
> As for methods signatures, I should probably get rid of the
> throws in the interface RandomData. How about RandomDataImpl? Would
> you rather have the exceptions in the method signature, or not?
I'm not sure either. People will look at the interface documentation, so
the javadoc here could notify about the exceptions if you feel inclined
to put them here. In all cases, it is better to have javadoc and throws
clause consistent (I think checkstyle may complain otherwise, depending
on its settings about checked/unchecked).
>
> Thanks for your advice, and I promise I'll clean up my mess ASAP.
Don't worry, you did not put any mess here. We (and especially I) put it
by ourselves ;-)
Luc
>
> Sébastien
>
>
> ---------------------------------------------------------------------
> 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
Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Sébastien Brisard <se...@m4x.org>.
Hello,
>
> 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
>
what I did in r1230906 was
1. make sure that exceptions actually thrown in RandomDataImpl are
identical with the @throws clause in the Javadoc of RandomData.
2. add the unchecked exceptions to the methods signatures.
>From what I understand, all exceptions should remain in the javadoc,
right? As for methods signatures, I should probably get rid of the
throws in the interface RandomData. How about RandomDataImpl? Would
you rather have the exceptions in the method signature, or not?
Thanks for your advice, and I promise I'll clean up my mess ASAP.
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Luc Maisonobe <Lu...@free.fr>.
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
Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random:
RandomData.java RandomDataImpl.java
Posted by Sébastien Brisard <se...@m4x.org>.
>
> This is not good style: Unchecked exceptions in method signatures do not
> offer any guarantee to the caller; 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?
>
Thanks for this clarification. I was merely referring to the
developer's guide, which should certainly be modified. I'm otherwise
happy to revert my changes (I do not like having unchecked exceptions
in the signature of a method).
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org