You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ps...@apache.org on 2011/02/01 01:23:48 UTC
svn commit: r1065874 -
/commons/proper/math/trunk/src/site/xdoc/developers.xml
Author: psteitz
Date: Tue Feb 1 00:23:48 2011
New Revision: 1065874
URL: http://svn.apache.org/viewvc?rev=1065874&view=rev
Log:
Added section on Exceptions.
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>
+ <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>
<subsection name='Unit Tests'>
<ul>
<li>
Re: svn commit: r1065874 -
/commons/proper/math/trunk/src/site/xdoc/developers.xml
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hi.
> > [...]
> >> + 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?
In general, I think that such a code is going to create headaches.
But let's discuss from a specific example. Do you have one?
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: svn commit: r1065874 - /commons/proper/math/trunk/src/site/xdoc/developers.xml
Posted by sebb <se...@gmail.com>.
On 1 February 2011 11:20, Gilles Sadowski <gi...@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
Re: svn commit: r1065874 -
/commons/proper/math/trunk/src/site/xdoc/developers.xml
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
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