You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Phil Steitz <ph...@gmail.com> on 2011/10/04 21:57:33 UTC
[math] advertising MathXxExceptions
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
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.
advertise Xxx
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)
con: users don't know they can catch the more specific exception
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] advertising MathXxExceptions
Posted by sebb <se...@gmail.com>.
On 4 October 2011 20:57, Phil Steitz <ph...@gmail.com> 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
> 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.
You could put:
@throws MathIAE (extends IAE) <condition causing throw>
or similar.
> advertise Xxx
> 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)
> con: users don't know they can catch the more specific exception
>
> Phil
>
> ---------------------------------------------------------------------
> 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: [math] advertising MathXxExceptions
Posted by sebb <se...@gmail.com>.
On 5 October 2011 02:05, Phil Steitz <ph...@gmail.com> 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.. Advertising MathIAE,
> which is noting more than an IAE with localized message, adds
> unnecessary complexity for the user, IMO.
Which is why I suggested documenting that MathIAE is IAE in the throws
clause - AFAICT that would be the best of both worlds.
> Phil
>>
>>>> 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
>>
>> ---------------------------------------------------------------------
>> 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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] advertising MathXxExceptions
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] advertising MathXxExceptions
Posted by Phil Steitz <ph...@gmail.com>.
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.. Advertising MathIAE,
which is noting more than an IAE with localized message, adds
unnecessary complexity for the user, IMO.
Phil
>
>>> 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
>
> ---------------------------------------------------------------------
> 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: [math] advertising MathXxExceptions
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
> > 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.
> >
> > 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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] advertising MathXxExceptions
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
On Tue, Oct 04, 2011 at 12:57:33PM -0700, Phil Steitz 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.
>
> 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)
> con: users don't know they can catch the more specific exception
>
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org