On Tue, Oct 04, 2011 at 06:05:12PM -0700, Phil Steitz wrote:
> On 10/4/11 4:26 PM, Gilles Sadowski wrote:
> >>> I have been leaving the standard exception advertisements alone as I
> >>> s/MathRuntimeException.createXxException/new MathXxException, but I
> >>> notice others are changing the @throws to declare the
> >>> MathXxException. We should probably be consistent. I don't know if
> >>> it really makes any difference. I see a pro and a con for each
> >>> approach:
> >>>
> >>> advertise MathXxx
> >> +1
> >> Rationale: CM documents what it does.
> >>
> >>> pro: users can catch / differentiate math-generated exceptions from
> >>> other standard exceptions of the same type up the stack
> >>> con: users may needlessly scratch heads or check javadoc to make
> >>> sure that, e.g. MathIAE *is* IAE, so they can skip the import and
> >>> catch IAE.
> > I don't understand the worry; either they read the Javadoc of a method and
> > can readily click on the link to see the exception Javadoc and its whole
> > hierarchy, or they read the source code and can open the corresponding Java
> > file to obtain the same information.
>
> The more users have to think about your code when using it, the less
> likely they are to use it and the less happy they will be when using
> it. Users should never have to look at the source to understand the
> API. This is one of the reasons that it is better to favor standard
> exceptions. Advertising IAE is clear and simple - no chasing down
> javadoc, no import, no thought required..
Users that don't want to catch exception do not "have to think" about it.
Users that do need to catch exceptions have to choose which one to handle;
hence they have to read the documentation and, like any other piece of
documentation, the one about the thrown exceptions should be as precise as
possible; documenting that a method throws a base class of what it actually
throws is incomplete (and misleading).
Suppose that for some reason, someone wants to only catch exceptions coming
from CM, then he'll indeed have to peer through the code in order to know
which type to insert in the catch clause.
As a low-level library, CM must document what it does, not what we imagine
that the user expects.
> Advertising MathIAE,
> which is noting more than an IAE with localized message, adds
> unnecessary complexity for the user, IMO.
I repeat that an exception instance should convey the nature of the failure
without having a human read the error message string.
This means that, usually, a method should throw an instance of a _subclass_
of "MathIllegalArgumentException".
There is absolutely no "unnecessary complexity for the user". There is
thorough information for those who'd need it.
For the use case that you seem to worry about (users that would catch
standard exception types), we could add a section in the user guide[1],
summarizing the relationships between CM exceptions and the standard ones.
> >
> >>> advertise Xxx
> >> -1
> >>
> >>> pro: follows "favor standard exceptions" practice and avoids need to
> >>> head scratch or import (also the ones that I am talking about are
> >>> really just the standard exceptions with localized
> >>> message-generation capability)
> > An exception instance should convey the nature of the failure without having
> > a human read the error message string.
> >
> >>> con: users don't know they can catch the more specific exception
> >>>
Gilles
[1] This should probably be done once the pending issues are settled.
[I had started to write it some months ago, just before what I intended
to describe was rendered obsolete...]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
