On Mon, 28 Jul 2025 17:13:48 GMT, fabioromano1 <d...@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
