On Wed, 21 Apr 2021 16:27:14 GMT, Joe Darcy <[email protected]> wrote:
> Just was we don't think it is helpful to put an explicit
>
> @throws NullPointerException if a argument is null
>
> on every method that throws a NPE for a null argument, I don't think it
> is helpful or necessary to explicitly note in every BigDecimal method
> with rounding that it could throw ArithmeticException. The general
> class-level statement
>
> ?* <p>As a 32-bit integer, the set of values for the scale is large,
> ?* but bounded. If the scale of a result would exceed the range of a
> ?* 32-bit integer, either by overflow or underflow, the operation may
> ?* throw an {@code ArithmeticException}.
>
> in meant to capture the needed information.
>
> -Joe
I do agree with this in general, but I think that the situation at hand is a
bit different from your example for two reasons:
* The `BigDecimal` class already contains many explicit `@throws` annotations
for `RuntimeException`s. The absence of such an annotation from a particular
method would thus naturally be interpreted as saying that the method does not
throw.
* For someone not intimately familiar with the internal representation of
`BigDecimal`s, it is probably quite unexpected that a function called
`stripTrailingZeros` would perform rounding and thus be liable to scale
overflows. (This is what happened to the maintainers of jackson-core, where
this lead to an unexpected RuntimeException that was only discovered via
fuzzing. They simply took this function to perform some kind of "harmless"
canonicalization.)
That is why I do see value in adding these annotations in this particular case.
-------------
PR: https://git.openjdk.java.net/jdk/pull/3189
