Apache/commons-math
1
0
Fork 0
mirror of https://github.com/apache/commons-math.git synced 2025-02-06 10:09:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added section on Exceptions.

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1065874 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Phil Steitz 2011-02-01 00:23:48 +00:00
parent 828e3db622
commit f301516390
1 changed files with 44 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
src/site/xdoc/developers.xml
View File

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