SONARJAVA-5580 modify S3024: add performance benchmark table

rules/S3024/java/rule.adoc

@@ -1,25 +1,85 @@
 == Why is this an issue?
 
-The use of a ``++StringBuilder++`` or ``++StringBuffer++`` is supposed to make ``++String++`` assembly more efficient than plain concatenation. So don't ruin the effect by concatenating the arguments to ``++append++``.
+The use of a ``++StringBuilder++`` or ``++StringBuffer++`` makes ``++String++`` assembly more efficient than plain concatenation when you perform a large number of appends.
+Using ``++String++`` concatenation within ``++StringBuilder.append++`` defeats the purpose of the ``++StringBuilder++``.
+If you concatenate only a few strings, use direct ``++String++`` concatenation.
+Otherwise, replace ``++String++`` concatenation with calls to ``++append++``.
 
 
 === Noncompliant code example
 
-[source,java]
+[source,java,diff-id=1,diff-type=noncompliant]
+----
+StringBuilder sb = new StringBuilder();
+String s = sb.append("foo is: " + getFoo()).toString(); // Noncompliant
+----
+
+[source,java,diff-id=2,diff-type=noncompliant]
 ----
 StringBuilder sb = new StringBuilder();
-sb.append("foo is: " + getFoo()); // Noncompliant
+for (String name : names) {
+  sb.append("Hello : " + name); // Noncompliant
+}
 ----
 
 
 === Compliant solution
 
-[source,java]
+[source,java,diff-id=1,diff-type=compliant]
+----
+String s = "foo is: " + getFoo();
+----
+
+[source,java,diff-id=2,diff-type=compliant]
 ----
 StringBuilder sb = new StringBuilder();
-sb.append("foo is: ").append(getFoo());
+for (String name : names) {
+  sb.append("Hello : ").append(name);
+}
 ----
 
+== Resources
+
+=== Benchmarks
+
+[options="header"]
+|===
+| Method| Runtime| Average time| Error margin
+| append| Temurin 21| 14.26 ns/op| ±0.50 ns/op
+| concat| Temurin 21| 17.77 ns/op| ±0.66 ns/op
+| concatWithinBuilder| Temurin 21| 31.42 ns/op| ±1.80 ns/op
+|===
+
+The results were generated by running the following snippet with https://github.com/openjdk/jmh[jmh]:
+
+[source,java]
+----
+private String name1 = "John";
+private String name2 = "Jane";
+
+@Benchmark
+public String concat() {
+  return name1 + ", " + name2;
+}
+
+@Benchmark
+public String concatWithinBuilder() {
+  return new StringBuilder()
+    .append(name1 + ", " + name2)
+    .toString();
+}
+
+@Benchmark
+public String append() {
+  return new StringBuilder()
+    .append(name1)
+    .append(", ")
+    .append(name2)
+    .toString();
+}
+----
+
+
 ifdef::env-github,rspecator-view[]
 
 '''