commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1065874 - /commons/proper/math/trunk/src/site/xdoc/developers.xml
Date Tue, 01 Feb 2011 00:23:48 GMT
Author: psteitz
Date: Tue Feb  1 00:23:48 2011
New Revision: 1065874

Added section on Exceptions.


Modified: commons/proper/math/trunk/src/site/xdoc/developers.xml
--- 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 @@
+   <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
+      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'>

View raw message