commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <gil...@harfang.homelinux.org>
Subject Re: svn commit: r1065874 - /commons/proper/math/trunk/src/site/xdoc/developers.xml
Date Tue, 01 Feb 2011 11:20:31 GMT
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.

> +      <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


Mime
View raw message