RFR: 8374540: Add comment describing implementaiton choices of Math.fma [v2]

[Joe Darcy]

On Tue, 6 Jan 2026 08:52:35 GMT, Eirik Bjørsnøs <eirbjo at openjdk.org> wrote:

>> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Respond to review feedback and add conclusion.
>
> src/java.base/share/classes/java/lang/Math.java line 2381:
> 
>> 2379:     @IntrinsicCandidate
>> 2380:     public static double fma(double a, double b, double c) {
>> 2381:         // Implementation note: this method is intentionally coded in
> 
> The note seems currently structured as:
> 
> * Actual implementation design
> * Hypothetical/alternative implementation design
> * Performance context
> * Actual implementation design ("-ilities")
> 
> The part suggesting how an alternative Java implementation could be made more performant seems counterproductive or at the least unnecessary.
> 
> I think the structure can be simplified as:
> 
> * Performance context
> * Actual implementation design/"-ilities"
> 
> Here's a sketch intended to demonstrate the suggested stucture (needs work for correctness, grammar, etc.):
> 
> 
>         // The Java implementation below will only be used when intrinsics
>         // using hardware fma support is not available.
>         // Therefore, simplicity, maintainability, and ease of testing
>         // of the code is more important than direct performance.
>         // The implementation is intentionally kept straightforward,
>         // relying on BigDecimal for numerical computation.

The intention of the PR is to avert future attempts to re-writing Math.fma to make it "faster"; see

https://mail.openjdk.org/pipermail/core-libs-dev/2025-December/156810.html

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

PR Review Comment: https://git.openjdk.org/jdk/pull/29044#discussion_r2665707030