commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <gil...@harfang.homelinux.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 11:32:29 GMT
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


Mime
View raw message