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

[Kevin Bourrillion]

On Thu, 11 Jul 2024 00:10:02 GMT, Stuart Marks <smarks 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.)

I would hope to spend as little space on this as possible, perhaps "This method should avoid throwing or propagating any exceptions unless it legitimately _cannot_ adhere to this contract."
(or shorter)

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

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