RFR: 8377446: Improve parameter naming in pointer_delta() [v2]

[Albert Mingkun Yang]

On Tue, 10 Feb 2026 10:44:12 GMT, Thomas Schatzl <tschatzl at openjdk.org> wrote:

>> src/hotspot/share/utilities/globalDefinitions.hpp line 440:
>> 
>>> 438: // Calculates the difference between the given high and low addresses, asserting
>>> 439: // on underflow.
>>> 440: //
>> 
>> This new doc makes it harder to reason about the arg ordering, IMO. I kind of prefer the original doc.
>
> Originally there has not been any documentation. Could you elaborate what this addition of the explanation of what the method does (first sentence) and the arguments (second sentence) make worse than no documentation of the arguments?
> 
> What was better before? It did not event explain what it did, what were expectations and failure mode.

"Difference" lacks directionality. Pointer subtraction is ordered (`high - low` != `low - high`); "difference" suggests `|a-b|`.

> What was better before? It did not event explain what it did,

`// Pointer subtraction.` is precise and to the point: it states exactly what this function does. Doc on failure modes are nice to have but not critical to callers at this level. Just my 2c.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/29631#discussion_r2787436251