commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [math] advertising MathXxExceptions
Date Wed, 05 Oct 2011 09:49:29 GMT
On 5 October 2011 02:05, Phil Steitz <phil.steitz@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


Mime
View raw message