On Wed, 21 Apr 2021 16:27:14 GMT, Joe Darcy <joe.da...@oracle.com> 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