RFR: 8336043: Add quality of implementation discussion to Object.{equals, toString, hashCode}

[Stuart Marks]

On Wed, 10 Jul 2024 22:33:54 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> First pass at adding some quality of implementation discussions around the overridable methods of Object.

src/java.base/share/classes/java/lang/Object.java line 53:

> 51:  * {@link VirtualMachineError} is possible during the execution of a
> 52:  * method, often due to factors outside of the method's direct
> 53:  * control.

"Should not throw any exception or other throwable" is overly broad. However, there is a narrower sense where code that implements these methods "shouldn't" throw anything. I'd suggest focusing on precondition checking. Specifically, no object should ever be in a state such that calling one of these methods results in IllegalStateException or other exception based on the state of the object. In addition, no argument passed to equals() should ever cause IllegalArgumentException, ClassCastException, NullPointerException, or other exception based on the argument.

(This comment applies to other locations where the "excessive" wording is used.)

src/java.base/share/classes/java/lang/Object.java line 191:

> 189:      * should not be thrown if the argument has an incomparable type
> 190:      * to this object and {@link NullPointerException} should not be
> 191:      * thrown if the argument is {@code null}.  The implementation

For these cases the recommendation should be to return false instead of throwing such exceptions.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/20128#discussion_r1673226617
PR Review Comment: https://git.openjdk.org/jdk/pull/20128#discussion_r1673227589