[prev in list] [next in list] [prev in thread] [next in thread] 

List:       jakarta-commons-user
Subject:    Re: [math] Where is the document on development guidelines?
From:       Phil Steitz <phil.steitz () gmail ! com>
Date:       2010-03-21 17:10:09
Message-ID: 4BA652F1.3020501 () gmail ! com
[Download RAW message or body]

Luc Maisonobe wrote:
> Disc Magnet a écrit :
>> On Sat, Mar 20, 2010 at 4:19 AM, Luc Maisonobe <Luc.Maisonobe@free.fr> wrote:
>>> Disc Magnet a écrit :
>>>> A few years back when I browsed the Apache Commons Math website, I found a
>>>> document describing how boundary cases, overflows, divide by zero, error
>>>> conditions, etc. are handled. They were some guidelines meant to be followed
>>>> by the developers of Commons Math. I am unable to locate this document now.
>>>> Could someone please help? Or is it that the guidelines are no longer
>>>> considered necessary?
>>>>
>>> Do you mean this page: <http://commons.apache.org/math/developers.html> ?
>>>
>>> Luc
>>>
>> Yes, but I don't find the guidelines regarding how to handle
>> overflows, divide by zero, error conditions, when to use NaN and such
>> things. Long back, I think the page had all this information. Can
>> someone please tell me where to read all this from?
> 
> Everything is in the web site. The page you refer to may have be
> rewritten since you last read it. As far as I know, there are no general
> guidelines for overflows and such. Several different algorithms use
> several different strategies, and we are not self consistent. For
> example, some algorithms deliberately use exact equality tests on
> doubles while others use a fixed tolerance for double comparisons and
> still others use user customizable tolerance. These behaviors are
> algorithm dependent. When we implement a well known algorithm, we try to
> keep these tests as they are in the reference implementation or paper,
> and the library has grown to a collection of sometimes inconsistent choices.
> 
> After some search (using grep ...) on the xml source files for the
> documentation, I really found only the developers.xml and overview.xml
> pages that are general enough and provide some hints about NaNs.
> 
> There were already some issues raised on inconsistencies
> (<http://issues.apache.org/jira/browse/MATH-194> and
> <http://issues.apache.org/jira/browse/MATH-195>), but we finally decided
> not to fix them. If you think it would be worth doing, patches are welcome.

The key is to fully document all behavior, as described in the
overview section.  When to return NaN, throw checked or unchecked
IllegalArgumentException exceptions really depends on what the API
is trying to express.  As Luc said, patches, suggestions for
improvement welcome.

Phil
> 
> Luc
> 
> 
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: user-unsubscribe@commons.apache.org
>> For additional commands, e-mail: user-help@commons.apache.org
>>
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: user-unsubscribe@commons.apache.org
> For additional commands, e-mail: user-help@commons.apache.org
> 


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

[prev in list] [next in list] [prev in thread] [next in thread]