Move ReplaceUnusedVariablesWithUnderscore to Java best practices

[timtebeek]

Developers pushed back on the Java 25 upgrade automatically replacing unused for-each/catch/lambda variable names with _, since automation cannot distinguish an intentionally-named variable from a genuinely unused one, and stripping the name removes useful context. This moves ReplaceUnusedVariablesWithUnderscore out of the UpgradeToJava25 version migration (java-version-25.yml) and into the opt-in JavaBestPractices recipe (java-best-practices.yml), alongside the other deliberately-applied lang restylings. As a result the standard Java 25 migration no longer rewrites unused variables to _, while teams that want the change can still get it by running JavaBestPractices or the recipe directly.

[timtebeek]

Why ReplaceUnusedVariablesWithUnderscore moved from the default Java 25 upgrade to opt-in best practices

The recipe rewrites provably unused variable names to _ in three places: enhanced-for loop variables, catch parameters, and lambda parameters. The transformation is technically correct, but applying it automatically across an entire codebase during a version upgrade drew consistent pushback. Representative cases:

Case 1 — Loop variable loses meaning

// before
for (var rowNum : rows) { total++; }
// after
for (var _ : rows) { total++; }

rowNum documents what's being iterated even when its value isn't read. Replacing it with _ removes that context for no functional gain.

Case 2 — Multi-parameter lambdas become unreadable

// before
map.forEach((key, value) -> count++);
// after
map.forEach((_, _) -> count++);

Repeated (_, _) was singled out as the hardest to read — at a glance you can no longer tell what the lambda is iterating over.

Case 3 — "Unused" ≠ "intentionally unused"

// before — name kept deliberately for a planned/near-future use
catch (IOException retryable) { fallback(); }
// after
catch (IOException _) { fallback(); }

Tooling can detect that a variable is currently unused, but not whether it was meant to be named (for clarity, an imminent change, or as a debugging anchor). _ signals deliberate intent the automation can't actually verify.

Case 4 — Debugging friction
A variable renamed to _ has to be re-introduced and re-named the moment someone needs to inspect it during troubleshooting, adding churn to exactly the moments that are already under pressure.

The underlying objection wasn't _ itself — it was the blanket, automated application. _ is genuinely useful applied selectively where intent is obvious (ignored exceptions, trivial loops/lambdas). It scales poorly when applied indiscriminately across whole files and systems.

Resolution: the recipe is no longer part of the default UpgradeToJava25 migration. It now lives in the opt-in JavaBestPractices recipe, so teams apply it deliberately and selectively rather than receiving it automatically with a version bump. The capability is preserved; only the "on by default" behavior was removed.