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: [Math] Exception handling (again)
Date Sun, 23 Jan 2011 22:57:28 GMT
Hi.

> > [...]
> > 
> >> Concerning point 1), there are two ways to advertise the exception.
> >> Javadoc only, or Javadoc plus throws clause. I personnaly would prefer
> >> Javadoc plus throws clause as it is simpler to make sure we didn't
> >> forget anything (using the trick of temporarily changing the base class
> >> for MathRuntimeException and look at compiler errors).
> > 
> > I'm against declaring runtime exception in "throws" clauses because it's
> > only useful for the trick you mention. If the documentation is consistent,
> > it is just redundant with it.
> 
> The goal is to be sure documentation is consistent and to have tools to
> check it.

I understand. But, as I have already said, this has drawbacks for the unwary
user, and because of this, it is advised against (also in Sun's guidelines,
I think).

> > Nothing prevents you from using your trick, but don't force the others to
> > follow non-standard coding guidelines ;-)
> 
> The problem with missing throws statements is that if someone tries to
> use this trick but someone else
                     ^^^^^^^
That's me. Doing that was also a lot of work, aimed at (from my standpoint)
cleaning up the code...

> removes the throws statements each time,
> this is a LOT of work to redo each time because there will be a lot of
> missing throws.

It shouldn't be done each time: Someone writes some code, he knows what
exceptions his code throws, and he documents them.
Of course, he can forget something, but you have to balance that with the
drawbacks of having misleading "throws" clauses.

> So if you don't want to add the throws statements yourself, you are free
> to ignore them, but please don't remove the ones others put as it
> simplifies their work.

OK. I won't delete them anymore (even if I still don't like them). But their
purpose should be mentioned somewhere (e.g. in these CM-specific guidelines
which everyone thought they were not necessary because we follow the
"standard" coding guidelines; which, obviously, is not true is this case).

Also, to reduce the amount of tedious work of commenting the trivial
cases, I propose that it is not mandatory to document occurrences of
"NullArgumentException" and "NoDataException": I think that it's sufficient
clue for the user to have their names appear in "throws" clause (even if the
argument is no explicitely mentioned).


Gilles

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


Mime
View raw message