[
https://issues.apache.org/jira/browse/MATH-854?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13598932#comment-13598932
]
Luc Maisonobe commented on MATH-854:
------------------------------------
Done for package analysis (almost) as of r1455194.
This is a daunting task. The trick to switch to checked exceptions temporarily
helps but has major drawbacks. It is impossible to simply use it and fix all
the errors that it triggers then switch back to unchecked exceptions. There are
cases when you clearly don't want to fix some errors, like for example when you
can prove an error will never be triggered. One simple example is:
{code}
public class Gaussian {
/**
* Gaussian with given normalization factor, mean and standard deviation.
*
* @param norm Normalization factor.
* @param mean Mean.
* @param sigma Standard deviation.
* @throws NotStrictlyPositiveException if {@code sigma <= 0}.
*/
public Gaussian(double norm, double mean, double sigma) throws
NotStrictlyPositiveException {
if (sigma <= 0) {
throw new NotStrictlyPositiveException(sigma);
}
...
}
/**
* Normalized gaussian with zero mean and unit standard deviation.
*/
public Gaussian() {
this(0, 1);
}
{code}
In the last constructor, we don't want to advertise
NotStrictlyPositiveException since you know 1 is positive. So when we use the
trick, we get a compilation error on the first constructor because of a missing
NotStrictlyPositiveException, fixed it as above by correctly declaring the
exception, and then we want to stop there, but there will still be a
compilation error for the last constructor.
Another case is when we have an implementation of an interface, like:
{code}
UnivariateFunction searchFunction = new UnivariateFunction() {
public double value(double x) {
if (checkPrecondition(x) {
throw new SomeOfOurInternalException(x);
}
return something;
}
}
{code}
Then, when we use the trick, we have to declare SomeOfOurInternalException in
the signature of value, but since it is defined by an interface, we have to
temporarily declare it at interface level (remembering that we will need to
remove it later on when we roll back from the trick). All of a sudden, *all*
uses of UnivariateFunction throughout the library will need to handle
SomeOfOurInternalException!
These two examples show the trick is not magic. It helps identifying were
problems lie, but it also creates a huge amount of false positive that must be
filtered manually. I have done that for the analysis package. I started with
about 2000 errors when I activated the trick. Then I started to solve the ones
from the analysis package one by one, going back to interfaces when needed,
letting some false positive as I detected them. At the end, I had more than
7900 errors, i.e. about 4 times more errors than when I started. So I rolled
back the trick, and still had to spend a few hours fixing the remaining
problems. Once everything was compiling again, I had to manually check a third
time what I had done by looking at the diff.
Well, at the end, it worked, but it is really difficult.
There are many other top level packages to handle, but I sincerely doubt we
will be able to go all way through. I will at least push the release to 4.0,
but think it will either be pushed further and further until we decide to give
up.
> Fill the "throws" clause of all methods
> ---------------------------------------
>
> Key: MATH-854
> URL: https://issues.apache.org/jira/browse/MATH-854
> Project: Commons Math
> Issue Type: Task
> Affects Versions: 3.0
> Reporter: Gilles
> Priority: Trivial
> Fix For: 3.2
>
>
> In discussions that led to this
> [thread|http://markmail.org/message/yu4lrnue54sncbek], it was concluded that
> by having the "throws" clause of all methods to contain _all_ exceptions
> possibly thrown (i.e. also the unchecked ones), it would be possible to
> ensure that the documentation is complete.
> This could be done by *temporarily* switching the base class
> "MathRuntimeException" (see MATH-853) to become a _checked_ exception and
> generating the CheckStyle report which will detect the mismatch between the
> Javadoc and the "throws" clause. (Thanks to Luc for this trick.)
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
