commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From S├ębastien Brisard <sebastien.bris...@m4x.org>
Subject [math] Documenting exceptions in interfaces (MATH-854)
Date Thu, 13 Sep 2012 06:27:22 GMT
Dear all,
in previous discussions, it was decided that Interfaces (and, I
suppose abstract methods) should *not* have a throws clause.
So, yesterday, I started modifying the javadoc of FieldVector. Each
"throws" clause was simply replaced by the following statement
"Implementations should throw [...] if [...]". Please have a look to
FieldVector and ArrayFieldVector for clarity.
This has several drawbacks

1. The javadoc of implementations must grow, since the implementer
must write something like

    /**
     * {@inheritDoc}
     *
     * @throws DimensionMismatchException if {@code v} is not the same size as
     * {@code this}.
     */

instead of simply writing /** {@inheritDoc} */.

2. The resulting javadoc of implementations is not satisfactory. For
example, the javadoc of FieldVector<T>.add(FieldVecto<T> v) now reads

// Begin Javadoc
Compute the sum of this and v. Implementations should throw
DimensionMismatchException if v is not the same size as this.

Specified by:
    add in interface FieldVector<T extends FieldElement<T>>
Parameters:
    v - vector to be added
Returns:
    this + v
Throws:
    DimensionMismatchException - if v is not the same size as this.
// End javadoc

The "should throw" statement should really not be here, but it is too
much of a hassle to rewrite the whole javadoc comment for each
implementation.

3. Using Luc's trick brings a whole lot of error messages

// Begin error message
Exception MathXxxException is not compatible with throws clause in [...]
// End error message

this is not really a problem, but it makes the whole process of
populating the throws clauses a bit difficult.

4. More importantly, there is *no way* to ensure that we actually
document all exceptions. Indeed, if we take for example
FieldVector<T>.mapDivide(T d)

The only reason we know we *have* to add MathArithmeticException to
the throws clause is because FieldElement (which is an interface)
*specifies* this exception in the throws clause of
FieldElement<T>.divide(<T>).
If this throws clause is removed from interfaces, then LUC'S TRICK
becomes useless. [1]

For all these reasons, I would advocate *specifying* in interfaces
exceptions which we know must occur. For example,
DimensionMismatchException will be in the signature of *all*
implementations of FieldVector.add(FieldVector). Why not add it to the
throws clause? The answer is likely to be "because it is bad
practice", but I think advertising unchecked exceptions is already a
bad practice. So I think if we go for a bad practice anyway, we should
do it *only if it makes our lives easier*. I don't think the current
state does.

On a more personal side, I'd like to say that I'm getting tired of
this issue. I have been working for days on the linear package, but
I'm making no progress, because each time I commit a change, I realize
this was not the proper thing to do because of new exchanges on the
ML. So I keep going back and forth. This is really sucking all of my
C-M time, while I'd like to be working on other issues (eg special
functions Gamma and Beta, visitors for FieldVectors, ...). That would
be perfectly fine if I could see the benefit of MATH-854. While this
seemed a good idea when we started discussing it, I'm not sure
anymore, now that we have really tried to implement MATH-854.

I'm sure that I'm not the only one among the regular developers to
spend so much time on this issue. Our powers are limited, and I really
would rather we had more time to concentrate on real (meaning,
numerical) issues.

S├ębastien

[1] MathArithmeticException in FieldElement.divide(FieldElement) is
probably not the best example, as Gilles noted inconsistencies
(Decimal64 and Complex do not throw an exception, but return NaN
instead).


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message