RFR: 8077587: BigInteger Roots [v52]

[Raffaello Giulietti]

On Mon, 28 Jul 2025 17:13:48 GMT, fabioromano1 <duke at openjdk.org> wrote:

>> src/java.base/share/classes/java/math/MutableBigInteger.java line 1993:
>> 
>>> 1991:              * non-significant bits), and the shift is performed in order to lose
>>> 1992:              * the smallest number of bits in the significand if necessary (minimizing loss of precision).
>>> 1993:              */
>> 
>> @fabioromano1 I've now spent several hours trying to "reverse engineer" (Java code -> maths) what is going on in the code below that tries to come up with a nice initial estimate of the end result, before starting Newton's loop.
>> I'm still not 100% sure I've got everything correctly, and whether each detail is mathematically sound.
>> The same will probably happen to other readers and maintainers in the future.
>> 
>> I understand the overall tactic described in the comment above. However, the details of the different (sub)cases deserve (and need) a more detailed documentation to help and guide future enhancements and fixes.
>> The best way, of course, is to use maths arguments whenever possible.
>
> @rgiulietti It would be helpful for me to know the points of the code (or the details) that are still not completly clear, since there are already some comments in the code, so I can know where to add others.

Sure, I'll try to point them out in the next days.

A trick that works for me, when attempting to comment my own code, is to imagine explaining it to a colleague or trying to anticipate the comments of a reviewer ;-) This includes everything not self-evident, details about correctness, readability, performance, etc. In summary, trying to put myself in my audience's place. In my experience, finding a good balance is not easy.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24898#discussion_r2237432706