Enrich recipe descriptions with rationale (#850)

* Enrich recipe descriptions with "why" rationale for RSPEC-tagged rules

The RSPEC tags on static analysis recipes used to link to SonarSource's
public rule documentation, but those URLs have been decommissioned.
Rather than adding broken links, this enriches each recipe's description
field with 1-2 sentences explaining why the issue matters — making the
recipes self-documenting. Descriptions for 98 recipes were updated;
9 were skipped because they already had thorough rationale.

* Reformat description strings to wrap at ~120 characters per line

Author: jkschneider

src/main/java/org/openrewrite/staticanalysis/AbstractClassPublicConstructor.java

@@ -34,7 +34,8 @@ public class AbstractClassPublicConstructor extends Recipe {
 
     @Getter
     final String description = "Constructors of `abstract` classes can only be called in constructors of their subclasses. " +
-            "Therefore the visibility of `public` constructors are reduced to `protected`.";
+            "Therefore the visibility of `public` constructors are reduced to `protected`. " +
+            "Declaring them `public` is misleading since it implies they could be invoked directly, which is never possible.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S5993");

src/main/java/org/openrewrite/staticanalysis/AddSerialVersionUidToSerializable.java

@@ -51,7 +51,8 @@ public class AddSerialVersionUidToSerializable extends Recipe {
 
     String description = "A `serialVersionUID` field is strongly recommended in all `Serializable` classes. If this is not " +
                 "defined on a `Serializable` class, the compiler will generate this value. If a change is later made " +
-                "to the class, the generated value will change and attempts to deserialize the class will fail.";
+                "to the class, the generated value will change and attempts to deserialize the class will fail. " +
+                "Explicitly declaring this field gives you control over binary compatibility across versions.";
 
     Set<String> tags = singleton("RSPEC-S2057");
 

src/main/java/org/openrewrite/staticanalysis/AtomicPrimitiveEqualsUsesGet.java

@@ -49,7 +49,12 @@ public class AtomicPrimitiveEqualsUsesGet extends Recipe {
     final String displayName = "Atomic Boolean, Integer, and Long equality checks compare their values";
 
     @Getter
-    final String description = "`AtomicBoolean#equals(Object)`, `AtomicInteger#equals(Object)` and `AtomicLong#equals(Object)` are only equal to their instance. This recipe converts `a.equals(b)` to `a.get() == b.get()`.";
+    final String description = "`AtomicBoolean#equals(Object)`, `AtomicInteger#equals(Object)` and " +
+            "`AtomicLong#equals(Object)` are only equal to their instance. " +
+            "This recipe converts `a.equals(b)` to `a.get() == b.get()`. " +
+            "These atomic classes do not override `equals` from `Object`, so calling it " +
+            "compares object identity rather than the wrapped value, which is almost never " +
+            "the intended behavior.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S2204");

src/main/java/org/openrewrite/staticanalysis/AvoidBoxedBooleanExpressions.java

@@ -33,8 +33,10 @@ public class AvoidBoxedBooleanExpressions extends Recipe {
     final String displayName = "Avoid boxed boolean expressions";
 
     @Getter
-    final String description = "Under certain conditions the `java.lang.Boolean` type is used as an expression, " +
-            "and it may throw a `NullPointerException` if the value is null.";
+    final String description = "Under certain conditions the `java.lang.Boolean` type is used as an " +
+            "expression, and it may throw a `NullPointerException` if the value is null. " +
+            "Using `Boolean.TRUE.equals(...)` guards against unboxing a `null` reference " +
+            "in control flow positions like `if` conditions and ternary operators.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S5411");

src/main/java/org/openrewrite/staticanalysis/BigDecimalDoubleConstructor.java

@@ -23,10 +23,15 @@
 
 @RecipeDescriptor(
         name = "`new BigDecimal(double)` should not be used",
-        description = "Use of `new BigDecimal(double)` constructor can lead to loss of precision. Use `BigDecimal.valueOf(double)` instead.\n" +
-                      "For example writing `new BigDecimal(0.1)` does not create a `BigDecimal` which is exactly equal to `0.1`, " +
-                      "but it is equal to `0.1000000000000000055511151231257827021181583404541015625`. " +
-                      "This is because `0.1` cannot be represented exactly as a double (or, for that matter, as a binary fraction of any finite length).",
+        description = "Use of `new BigDecimal(double)` constructor can lead to loss of precision. " +
+                      "Use `BigDecimal.valueOf(double)` instead.\n" +
+                      "For example writing `new BigDecimal(0.1)` does not create a `BigDecimal` " +
+                      "which is exactly equal to `0.1`, but it is equal to " +
+                      "`0.1000000000000000055511151231257827021181583404541015625`. " +
+                      "This is because `0.1` cannot be represented exactly as a double " +
+                      "(or, for that matter, as a binary fraction of any finite length). " +
+                      "`BigDecimal.valueOf` avoids this by converting through a string " +
+                      "representation, preserving the value you actually intended.",
         tags = {"RSPEC-S2111"}
 )
 public class BigDecimalDoubleConstructor {

src/main/java/org/openrewrite/staticanalysis/BigDecimalRoundingConstantsToEnums.java

@@ -42,7 +42,10 @@ public class BigDecimalRoundingConstantsToEnums extends Recipe {
     final String displayName = "`BigDecimal` rounding constants to `RoundingMode` enums";
 
     @Getter
-    final String description = "Convert `BigDecimal` rounding constants to the equivalent `RoundingMode` enum.";
+    final String description = "Convert `BigDecimal` rounding constants to the equivalent " +
+            "`RoundingMode` enum. The integer-based rounding constants on `BigDecimal` " +
+            "are deprecated and lack type safety; the `RoundingMode` enum makes the " +
+            "rounding behavior self-documenting and prevents invalid values.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S2111");

src/main/java/org/openrewrite/staticanalysis/BooleanChecksNotInverted.java

@@ -33,7 +33,10 @@ public class BooleanChecksNotInverted extends Recipe {
     final String displayName = "Boolean checks should not be inverted";
 
     @Getter
-    final String description = "Ensures that boolean checks are not unnecessarily inverted. Also fixes double negative boolean expressions.";
+    final String description = "Ensures that boolean checks are not unnecessarily inverted. " +
+            "Also fixes double negative boolean expressions. Negating a comparison and " +
+            "then inverting it adds cognitive overhead; using the direct operator " +
+            "(e.g., `>=` instead of `!(... < ...)`) is clearer and easier to reason about.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S1940");

src/main/java/org/openrewrite/staticanalysis/CaseInsensitiveComparisonsDoNotChangeCase.java

@@ -41,7 +41,8 @@ public class CaseInsensitiveComparisonsDoNotChangeCase extends Recipe {
     final String displayName = "CaseInsensitive comparisons do not alter case";
 
     @Getter
-    final String description = "Remove `String#toLowerCase()` or `String#toUpperCase()` from `String#equalsIgnoreCase(..)` comparisons.";
+    final String description = "Remove `String#toLowerCase()` or `String#toUpperCase()` from `String#equalsIgnoreCase(..)` comparisons. " +
+            "Changing case before a case-insensitive comparison is redundant and allocates unnecessary intermediate `String` objects.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S1157");

src/main/java/org/openrewrite/staticanalysis/CatchClauseOnlyRethrows.java

@@ -39,7 +39,8 @@ public class CatchClauseOnlyRethrows extends Recipe {
 
     @Getter
     final String description = "A `catch` clause that only rethrows the caught exception is unnecessary. " +
-            "Letting the exception bubble up as normal achieves the same result with less code.";
+            "Letting the exception bubble up as normal achieves the same result with less code. " +
+            "Such catch blocks add visual noise and indentation without changing program behavior.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S2737");

src/main/java/org/openrewrite/staticanalysis/ChainStringBuilderAppendCalls.java

@@ -39,7 +39,12 @@ public class ChainStringBuilderAppendCalls extends Recipe {
     final String displayName = "Chain `StringBuilder.append()` calls";
 
     @Getter
-    final String description = "String concatenation within calls to `StringBuilder.append()` causes unnecessary memory allocation. Except for concatenations of String literals, which are joined together at compile time. Replaces inefficient concatenations with chained calls to `StringBuilder.append()`.";
+    final String description = "String concatenation within calls to `StringBuilder.append()` " +
+            "causes unnecessary memory allocation. Except for concatenations of String " +
+            "literals, which are joined together at compile time. Replaces inefficient " +
+            "concatenations with chained calls to `StringBuilder.append()`. " +
+            "Using `+` inside `append()` defeats the purpose of the `StringBuilder`, " +
+            "since the concatenation creates a temporary `String` before appending.";
 
     @Getter
     final Set<String> tags = singleton("RSPEC-S3024");