SONARJAVA-4524 Update rules metadata (#4408)

Author: alban-auzeill

its/ruling/src/test/java/org/sonar/java/it/AutoScanTest.java

@@ -188,7 +188,7 @@ public void javaCheckTestSources() throws Exception {
      * No differences would mean that we find the same issues with and without the bytecode and libraries
      */
     String differences = Files.readString(pathFor(TARGET_ACTUAL + PROJECT_KEY + "-no-binaries_differences"));
-    assertThat(differences).isEqualTo("Issues differences: 3269");
+    assertThat(differences).isEqualTo("Issues differences: 3265");
   }
 
   private static Path pathFor(String path) {

its/ruling/src/test/resources/autoscan/autoscan-diff-by-rules.json

@@ -161,12 +161,6 @@
     "falseNegatives": 0,
     "falsePositives": 0
   },
-  {
-    "ruleKey": "S1114",
-    "hasTruePositives": true,
-    "falseNegatives": 0,
-    "falsePositives": 0
-  },
   {
     "ruleKey": "S1116",
     "hasTruePositives": true,
@@ -587,12 +581,6 @@
     "falseNegatives": 11,
     "falsePositives": 0
   },
-  {
-    "ruleKey": "S1610",
-    "hasTruePositives": true,
-    "falseNegatives": 4,
-    "falsePositives": 0
-  },
   {
     "ruleKey": "S1611",
     "hasTruePositives": true,

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S100.html

@@ -1,18 +1,18 @@
 <h2>Why is this an issue?</h2>
-<p>Shared naming conventions allow teams to collaborate efficiently. This rule checks that all method names match a provided regular expression.</p>
-<h3>Noncompliant code example</h3>
-<p>With default provided regular expression <code>^[a-z][a-zA-Z0-9]*$</code>:</p>
+<p>Shared naming conventions allow teams to collaborate efficiently.</p>
+<p>This rule raises an issue when a method name does not match a provided regular expression.</p>
+<p>For example, with the default provided regular expression <code>^[a-z][a-zA-Z0-9]*$</code>, the method:</p>
 <pre>
-public int DoSomething(){...}
+public int DoSomething(){...} // Noncompliant
 </pre>
-<h3>Compliant solution</h3>
+<p>should be renamed to</p>
 <pre>
 public int doSomething(){...}
 </pre>
 <h3>Exceptions</h3>
 <p>Overriding methods are excluded.</p>
 <pre>
 @Override
-public int Do_Something(){...}
+public int Do_Something(){...} // Compliant by exception
 </pre>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S101.html

@@ -1,12 +1,11 @@
 <h2>Why is this an issue?</h2>
-<p>Shared coding conventions allow teams to collaborate effectively. This rule allows to check that all class names match a provided regular
-expression.</p>
-<h3>Noncompliant code example</h3>
-<p>With default provided regular expression <code>^[A-Z][a-zA-Z0-9]*$</code>:</p>
+<p>Shared naming conventions allow teams to collaborate efficiently.</p>
+<p>This rule raises an issue when a class name does not match a provided regular expression.</p>
+<p>For example, with the default provided regular expression <code>^[A-Z][a-zA-Z0-9]*$</code>, the class:</p>
 <pre>
-class my_class {...}
+class my_class {...} // Noncompliant
 </pre>
-<h3>Compliant solution</h3>
+<p>should be renamed to</p>
 <pre>
 class MyClass {...}
 </pre>

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S103.html

@@ -1,3 +1,3 @@
 <h2>Why is this an issue?</h2>
-<p>Having to scroll horizontally makes it harder to get a quick overview and understanding of any piece of code.</p>
+<p>Scrolling horizontally to see a full line of code lowers the code readability.</p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S104.html

@@ -1,5 +1,6 @@
 <h2>Why is this an issue?</h2>
-<p>A source file that grows too much tends to aggregate too many responsibilities and inevitably becomes harder to understand and therefore to
-maintain. Above a specific threshold, it is strongly advised to refactor it into smaller pieces of code which focus on well defined tasks. Those
-smaller files will not only be easier to understand but also probably easier to test.</p>
+<p>A source file that grows too much tends to aggregate too many responsibilities and inevitably becomes harder to understand and, therefore, to
+maintain.</p>
+<p>Above a specific threshold, refactor the file into smaller files whose code focuses on well-defined tasks. Those smaller files will be easier to
+understand and easier to test.</p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S105.html

@@ -1,4 +1,5 @@
 <h2>Why is this an issue?</h2>
-<p>Developers should not need to configure the tab width of their text editors in order to be able to read source code.</p>
-<p>So the use of the tabulation character must be banned.</p>
+<p>The tab width can differ from one development environment to another. Using tabs may require other developers to configure their environment (text
+editor, preferences, etc.) to read source code.</p>
+<p>That is why using spaces is preferable.</p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S108.html

@@ -1,10 +1,10 @@
 <h2>Why is this an issue?</h2>
-<p>Most of the time a block of code is empty when a piece of code is really missing. So such empty block must be either filled or removed.</p>
-<h3>Noncompliant code example</h3>
+<p>An empty code block is confusing. It will require some effort from maintainers to determine if it is intentional or indicates the implementation is
+incomplete.</p>
 <pre>
-for (int i = 0; i &lt; 42; i++){}  // Empty on purpose or missing piece of code ?
+for (int i = 0; i &lt; 42; i++){}  // Noncompliant: is the block empty on purpose, or is code missing?
 </pre>
+<p>Removing or filling the empty code blocks takes away ambiguity and generally results in a more straightforward and less surprising code.</p>
 <h3>Exceptions</h3>
-<p>When a block contains a comment, this block is not considered to be empty unless it is a <code>synchronized</code> block. <code>synchronized</code>
-blocks are still considered empty even with comments because they can still affect program flow.</p>
+<p>The rule ignores code blocks that contain comments unless they are <code>synchronized</code> blocks because these can affect program flow.</p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S110.html

@@ -1,22 +1,22 @@
 <h2>Why is this an issue?</h2>
-<p>Inheritance is certainly one of the most valuable concepts in object-oriented programming. It’s a way to compartmentalize and reuse code by
-creating collections of attributes and behaviors called classes which can be based on previously created classes. But abusing this concept by creating
-a deep inheritance tree can lead to very complex and unmaintainable source code. Most of the time too deep of an inheritance tree is due to bad object
-oriented design which leads to a systematic use of 'inheritance' when 'composition' would be better suited.</p>
-<p>This rule raises an issue when the inheritance tree, starting from <code>Object</code> has a greater depth than is allowed.</p>
-<p>For the parameter of the rule, the following rules are applied:</p>
+<p>Inheritance is one of the most valuable concepts in object-oriented programming. It’s a way to categorize and reuse code by creating collections of
+attributes and behaviors called classes, which can be based on previously created classes.</p>
+<p>But abusing this concept by creating a deep inheritance tree can lead to complex and unmaintainable source code. Often, an inheritance tree
+becoming too deep is the symptom of systematic use of "inheritance" when other approaches like "composition" would be better suited.</p>
+<p>This rule raises an issue when the inheritance tree, starting from <code>Object</code>, has a greater depth than is allowed.</p>
+<p>The rule has one parameter to filter out classes of the count of inheritance. The following rules apply to define this parameter:</p>
 <ul>
   <li> <code>?</code> matches a single character </li>
   <li> <code>*</code> matches zero or more characters </li>
   <li> <code>**</code> matches zero or more packages </li>
 </ul>
 <p>Examples:</p>
 <ul>
-  <li> <code>java.fwk.AbstractFwkClass</code> will stop count when AbstractFwkClassclass is reached. </li>
-  <li> <code>java.fwk.*</code> will stop count when any member of java.fwkPackage package is reached. </li>
-  <li> <code>java.fwk.**</code> same as above, but including sub-packages. </li>
+  <li> <code>java.fwk.AbstractFwkClass</code>: the count stops when AbstractFwkClass class is reached. </li>
+  <li> <code>java.fwk.*</code>: any member of java.fwkPackage package is reached. </li>
+  <li> <code>java.fwk.**</code>: same as above, but including sub-packages. </li>
 </ul>
-<p>Exceptions:</p>
+<h2>Exceptions:</h2>
 <p>The rule stops counting when it encounters a class from one of the following packages (or sub-packages):</p>
 <ul>
   <li> <code>android.**</code> </li>
@@ -26,4 +26,8 @@ <h2>Why is this an issue?</h2>
   <li> <code>org.eclipse.**</code> </li>
   <li> <code>org.springframework.**</code> </li>
 </ul>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<p><a href="https://en.wikipedia.org/wiki/Composition_over_inheritance">Composition over inheritance: difference between composition and inheritance
+in object-oriented programming</a></p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S1111.html

@@ -1,6 +1,13 @@
 <h2>Why is this an issue?</h2>
-<p>According to the official javadoc documentation, this Object.finalize() is called by the garbage collector on an object when garbage collection
-determines that there are no more references to the object. Calling this method explicitly breaks this contract and so is misleading.</p>
+<p>Before it reclaims storage from an object that is no longer referenced, the garbage collector calls <code>finalize()</code> on the object.</p>
+<p>This is a good time to release resources held by the object.</p>
+<p>Because the general contract is that the <code>finalize</code> method should only be called once per object, calling this method explicitly is
+misleading and does not respect this contract.</p>
+<h3>What is the potential impact?</h3>
+<p>An explicit call to an object’s finalize method will perform operations that most likely were supposed to be performed only when the object was not
+referenced anymore by any thread.</p>
+<p>Since it is an acceptable practice to override the finalize method in any subclass of <code>Object</code>, by invoking it explicitly, we will run
+code that was designed to only be ran at a different time.</p>
 <h3>Noncompliant code example</h3>
 <pre>
 public void dispose() throws Throwable {
@@ -9,6 +16,7 @@ <h3>Noncompliant code example</h3>
 </pre>
 <h2>Resources</h2>
 <ul>
+  <li> <a href="https://docs.oracle.com/javase/specs/jls/se17/html/jls-12.html#jls-12.6">docs.oracle.com</a> - Finalization of Class Instances </li>
   <li> <a href="https://cwe.mitre.org/data/definitions/586">MITRE, CWE-586</a> - Explicit Call to Finalize() </li>
   <li> <a href="https://wiki.sei.cmu.edu/confluence/x/4jZGBQ">CERT, MET12-J.</a> - Do not use finalizers </li>
 </ul>