commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: svn commit: r1065874 - /commons/proper/math/trunk/src/site/xdoc/developers.xml
Date Tue, 01 Feb 2011 12:36:17 GMT
On 1 February 2011 11:20, Gilles Sadowski <gilles@harfang.homelinux.org> wrote:
> Hi.
>
>> Added section on Exceptions.
>
> I agree with the explanations; however I think that we should add a paragraph
> (see below).
>
>> Modified:
>>     commons/proper/math/trunk/src/site/xdoc/developers.xml
>>
>> Modified: commons/proper/math/trunk/src/site/xdoc/developers.xml
>> URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/developers.xml?rev=1065874&r1=1065873&r2=1065874&view=diff
>> ==============================================================================
>> --- commons/proper/math/trunk/src/site/xdoc/developers.xml (original)
>> +++ commons/proper/math/trunk/src/site/xdoc/developers.xml Tue Feb  1 00:23:48 2011
>> @@ -183,6 +183,50 @@
>>        Guide.</li>
>>      </ul>
>>     </subsection>
>> +   <subsection name='Exceptions'>
>> +    <ul>
>> +      <li>
>> +      Exceptions generated by Commons Math are all unchecked.</li>
>> +      <li>
>> +      All public methods advertise all exceptions that they can generate.
>> +      Exceptions <i>must</i> be documented in both javadoc and method
signatures
>> +      and the documentation in the javadoc <i>must</i> include full
description
>> +      of the conditions under which exceptions are thrown.</li>
>> +      <li>
>> +      All exceptions inherit from the base class, MathRuntimeException.</li>
>> +      <li>
>> +      Methods <i>should</i> fully specify parameter preconditions
required for
>> +      successful activation.  When preconditions are violated, a
>> +      MathIllegalArgumentException should be thrown.  Subclasses of
>> +      MathIllegalArgumentException may be used to represent common parameter
>> +      contract violations (for example, NoBracketingException).  Exception
>> +      messages <i>must</i> contain sufficient information on parameter
values to
>> +      determine the exact precondition failure.</li>
>> +      <li>
>> +      Exceptions generated by Commons Math make sense without knowing
>> +      implementation details other than those stated in the public API.
>> +      For example, a NoBracketingException makes sense thrown by a solver that
>> +      has a precondition requiring that initial points bracket a root. This
>> +      exception does not make sense, however, thrown by an inverse cumulative
>> +      probability estimator.</li>
>> +      <li>
>> +      MathIllegalArgumentException should only be thrown in situations
>> +      where preconditions can be exhaustively provided so that what arguments
>> +      are "illegal" can be specified fully to the caller. Domain-specific
>> +      exceptions need to be defined for cases where failures cannot be
>> +      attributed to parameter precondition violation. For example, the exact
>> +      domain of successful activation of a solver or quadrature method may be
>> +      impossible to specify because of numerical properties of the method.
>> +      If a solver fails to find a root or a quadrature method fails to converge
>> +      for a given set of parameters, <i>unless those parameters violate
the
>> +      advertised preconditions</i> it is not appropriate to throw
>> +      MathIllegalArgumentException.</li>
>
>  If the failure results from an exception thrown by user code (e.g. an
>  exception is thrown while a solver is evaluating a user-defined function),
>  the Commons Math code must let it propagate without interference.

That may not be possible in general.

If the user code generates an Exception that CM already handles, how
can CM distinguish this case?


>> +      <li>
>> +      State information included in exception messages <i>must</i>
be available
>> +      in exception properties - i.e., successful handling or reporting of
>> +      Commons Math exceptions must not require parsing exception messages.</li>
>> +     </ul>
>> +   </subsection>
>
>
> 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


Mime
View raw message