Subtraction in 'compareTo()'

Reports subtraction in compareTo() methods and methods implementing java.util.Comparator.compare().

While it is a common idiom to use the results of integer subtraction as the result of a compareTo() method, this construct may cause subtle and difficult bugs in cases of integer overflow. Comparing the integer values directly and returning -1, 0, or 1 is a better practice in most cases.

Subtraction on floating point values that is immediately cast to integral type is also reported because precision loss is possible due to rounding.

The inspection doesn't report when it's statically determined that value ranges are limited, and overflow never occurs. Additionally, subtraction on int numbers greater than or equal to 0 will never overflow. Therefore, this inspection tries not to warn in those cases.

Methods that always return zero or greater can be marked with the javax.annotation.Nonnegative annotation or specified in this inspection's options.

Example:

A no-warning example because String.length() is known to be non-negative:

Use the options to list methods that are safe to use inside a subtraction. Methods are safe when they return an int value that is always greater than or equal to 0.