Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (nike.apache.org: local policy)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 7bit
Date: Tue, 05 Nov 2013 14:21:51 +0100
From: Gilles <gilles@harfang.homelinux.org>
To: <dev@commons.apache.org>
Subject: Re: [MATH] Interest in large patches for small cleanup /
 performance =?UTF-8?Q?changes=3F?=
In-Reply-To: <5277F0ED.7050905@gmail.com>
References: 
 <CAEccTyzHd8hJ=N=3tL7hAWW9N_xJWf0egx9ADePrw9d5zmpY=Q@mail.gmail.com>
 <868f896a9b0fec839efc24f3847d82ed@scarlet.be>
 <CAEccTyxXgNiREC0B8E7MOUKgaP57WEi3Ed+gKTbHoRxvLikm0g@mail.gmail.com>
 <52752D17.2040003@gmail.com>
 <CAEccTyxRtpUK8DmFsz39SvsgfEaJfE6EnmT2tKWb=2737SV_Mg@mail.gmail.com>
 <e732ec702795a9537c2c4a309b05988a@scarlet.be>
 <52769C5E.9070903@spaceroots.org>
 <CAJwFCa0YKAthnuWShhD+1R70XiUoNNssWYx4mUV616GmpX4UmQ@mail.gmail.com>
 <5276ABF6.10602@spaceroots.org>
 <9ad805c2301511fe4771d5f53e84e27c@scarlet.be> <5276DD38.3000900@gmail.com>
 <178c2fe8add6e6fc126cc08e02f77655@scarlet.be>
 <52777218.1060102@spaceroots.org> <5277DDB4.1070205@gmail.com>
 <e7647bffe38706ea7aaa38c3efe942f8@scarlet.be> <5277F0ED.7050905@gmail.com>
Message-ID: <618e9921dc957cd8f29f3daf91d470be@scarlet.be>
User-Agent: Scarlet Webmail
X-DCC-scarlet.be-Metrics: eir; whitelist
X-Virus-Scanned: clamav-milter 0.97.1-exp at eir
X-Virus-Status: Clean
X-Virus-Checked: Checked by ClamAV on apache.org

>>> [...]
>>> I have scanned for exact duplicates quite a few times and never
>>> found any.  There are quite a few that are similar, but differ in
>>> material ways (strict versus non-strict inequalities, endpoints
>>> included / not included, etc.).  Please do not "collapse" messages
>>> at the expense of loss of specificity or correctness.
>>
>> FAILED_BRACKETING
>> UNABLE_TO_BRACKET_OPTIMUM_IN_LINE_SEARCH
>> INVALID_BRACKETING_PARAMETERS
>
> Look at the messages.  These are different.  They convey different
> information and are appropriate in different contexts.  See below.

I've argued that context information should be constructed at the
point where the exception is thrown (where the context is known).
Not all combinations of exceptions and context need be present in
the pattern list.
This is the essence of my proposal below.

>>
>> My position: the error (failed bracketing) should have its own
>> exception
>> type. The varying contexts could (do not have to) be part of the
>> message
>> built at exception instantiation.
>>
>> If we want to include an indication of location (despite it is
>> already
>> part of the stack trace, so it is _redundant_), we could perhaps
>> add methods
>> to the "ExceptionContext", e.g. "where(LocalizeFormats pattern)" 
>> (?).
>> Then, we would have thos patterns in the list:
>>
>> BRACKETING
>> LINE_SEARCH
>>
>> Note: INVALID and FAILED are redundant since the pattern is
>> intended to be
>> included in an exception.
>>
>>
>> A second "interesting" case is
>>
>> INVALID_ROUNDING_METHOD
>>
>> which mixes documentation with error description. Does anyone
>> really thinks
>> that the enumeration of the rounding methods in the error message
>> is necessary
>> or even helpful?
>
> When I throw an exception, I want to provide an error message that
> is meaningful in the context of the caller, i.e., that someone
> looking at a log or stack trace can make sense of.  That sometimes
> means restating preconditions, sometimes pointing to boundary
> conditions, sometimes giving hints describing common causes of the
> exception - lots of different things that depend on the API, the
> activation context and the nature of the exception.  The natural way
> to do this is to use natural language sentences.  Please allow me to
> retain a straightforward way to construct these messages and to
> maintain the specificity and meaning of the messages.

IMHO, the level of details in the message is not needed: if the 
exception
was thrown, the user should probably look at the documentation, rather
than try another value at random; I'd say that it is harmful to tempt 
the
users with something like "Pick another number". ;-)

[Shouldn't we rather provide function where the rounding type is an 
enum?]

The main problem in those discussions is that you consider only "toy"
situations, where the message generated by Commons Math should make 
sense
wherever the exception is caught, and even if it is not caught.
[I sometimes get a "failed bracketing" but knowing the values of "the
endpoints [that] have the same sign" does not really help. I'd rather 
need
to catch the exception, add more context info, rethrow, recatch, etc.
And all this is quite more expensive than activating logging for those
rare cases where numerical problems in the simulation trigger the
exception.]
Again and again, I do not mean that CM should not generate error 
messages,
only that context info beyond a plain description of what happened is
rarely usable a few layers above the failed call. And that context info
could be provided with much less than 300+ different messages.

Having little "building blocks" would also make it easier to retrieve
pattern/value pairs, as Luc seems willing to do, and more stable, since
a single placeholder is unlikely to change meaning, while a sentence 
that
contains many, could be turned differently so that the previous 
placeholder
index could now refer to a different value.


Gilles


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