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-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
