On 11/5/10 5:39 PM, Gilles Sadowski wrote:
Hello.
[...]
Of course, I didn't overlook that you just ask for a
@throws FunctionEvaluationException when the evaluation failed.
Javadoc comment.
I'm just reluctant to publicize a guideline that is not adhered to in CM!
Whenever a method is passed an argument that doesn't fulfill pre-conditions,
it throws an "IllegalArgumentException". But "FunctionEvaluationException"
is not a subclass of "IllegalArgumentException". Users who are passed a
"UnivariateRealFunction" instance should not rely that catching
"FunctionEvaluationException" will work in most cases!
So, should the Javadoc in fact be
@throws IllegalArgumentException when the evaluation failed because
of an invalid argument.
@throws FunctionEvaluationException when the evaluation failed for any
other reason.
?
In the cases where we know both are possible, yes, including as much
context- or algorithm-specific information as possible in each
throws clause.
I somewhat reluctantly agreed to dispense with checked exceptions,
but we absolutely need to document the unchecked exceptions that we
know can be thrown by [math]. The examples that Luc refers to above
and the usefulness in general of the FunctionEvaluationException are
consequences of the layered structure of the library and inclusion
of user code "sandwiched" as he describes it within the [math]
frameworks.
Then, how do you extend your guidelines to make it clear when to use one or
the other?
+1 - here is an idea that can likely be improved:
IllegalArgumentException - thrown when the activated method itself
can ascertain that preconditions specified in the API expressed at
the level of the activated method have been violated. In the vast
majority of cases where [math] throws IllegalArgumentException, it
is the result of argument checking of actual parameters immediately
passed to a method.
FunctionEvaluationException - may be advertised by a method that may
encounter errors evaluating a function. This *should* be thrown
only in circumstances where at the level of the activated function
IllegalArgumentException is not appropriate and it *should* indicate
that while formal preconditions of the method have not been
violated, an irrecoverable error has occurred evaluating a function
at some (usually lower) level of the call stack. Convergence
failures, runtime exceptions (even IllegalArgumentExceptions) in
user code or lower level methods can cause (and should be wrapped
in) FunctionEvaluationExceptions.
You could write a document that would explain how good it would be if all
programs were using the same exceptions. But I must point out that CM isn't
a good example, with its policy of no dependencies. Why would anyone depend
on CM just for the sake of using CM exceptions?
I think you are missing the point here - our APIs can encourage
consistent use of exceptions by user code that uses and/or
integrates with [math].
These are the kinds of things we need to talk about in refactoring
exceptions. Our API - including all advertised exceptions - needs
to help users understand what we - and they - are doing, not just
minimize the amount of code they need to write or simplify our lives
as maintainers. This is especially true of the more complex
algorithms and frameworks where user code plugs into [math].
Phil
Best regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
