SONARJAVA-4499 Update rules metadata (#4392)

* SONARJAVA-4499 Update rules metadata, rename sections

* SONARJAVA-4499 Update rules metadata, deprecated rules

* SONARJAVA-4499 Update rules metadata, "See Also" sections

* SONARJAVA-4499 S2384 description updated to match the implementation

* SONARJAVA-4499 Fix S2755 rule description invalid section

* SONARJAVA-4499 Migrate S3981 rule description to the educational format

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

@@ -1,14 +1,15 @@
+<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>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <p>With default provided regular expression <code>^[a-z][a-zA-Z0-9]*$</code>:</p>
 <pre>
 public int DoSomething(){...}
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public int doSomething(){...}
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>Overriding methods are excluded.</p>
 <pre>
 @Override

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

@@ -1,11 +1,12 @@
+<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>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <p>With default provided regular expression <code>^[A-Z][a-zA-Z0-9]*$</code>:</p>
 <pre>
 class my_class {...}
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 class MyClass {...}
 </pre>

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

@@ -1,2 +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>
 

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

@@ -1,3 +1,4 @@
+<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>

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

@@ -1,3 +1,4 @@
+<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>
 

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

@@ -1,3 +1,4 @@
+<h2>Why is this an issue?</h2>
 <p>When logging a message there are several important requirements which must be fulfilled:</p>
 <ul>
   <li> The user must be able to easily retrieve the logs </li>
@@ -7,15 +8,15 @@
 </ul>
 <p>If a program directly writes to the standard outputs, there is absolutely no way to comply with those requirements. That’s why defining and using a
 dedicated logger is highly recommended.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 System.out.println("My Message");  // Noncompliant
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 logger.log("My Message");
 </pre>
-<h2>See</h2>
+<h2>Resources</h2>
 <ul>
   <li> <a href="https://owasp.org/Top10/A09_2021-Security_Logging_and_Monitoring_Failures/">OWASP Top 10 2021 Category A9</a> - Security Logging and
   Monitoring Failures </li>

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

@@ -1,6 +1,7 @@
+<h2>Why is this an issue?</h2>
 <p>If a label is declared but not used in the program, it can be considered as dead code and should therefore be removed.</p>
 <p>This will improve maintainability as developers will not wonder what this label is used for.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 void foo() {
   outer: //label is not used.
@@ -9,15 +10,15 @@ <h2>Noncompliant Code Example</h2>
   }
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 void foo() {
   for(int i = 0; i&lt;10; i++) {
     break;
   }
 }
 </pre>
-<h2>See</h2>
+<h2>Resources</h2>
 <ul>
   <li> <a href="https://wiki.sei.cmu.edu/confluence/x/5dUxBQ">CERT, MSC12-C.</a> - Detect and remove code that has no effect or is never executed
   </li>

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

@@ -1,13 +1,14 @@
+<h2>Why is this an issue?</h2>
 <p>Merging collapsible <code>if</code> statements increases the code’s readability.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 if (file != null) {
   if (file.isFile() || file.isDirectory()) {
     /* ... */
   }
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 if (file != null &amp;&amp; isFileOrDirectory(file)) {
   /* ... */

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

@@ -1,16 +1,17 @@
+<h2>Why is this an issue?</h2>
 <p>The complexity of an expression is defined by the number of <code>&amp;&amp;</code>, <code>||</code> and <code>condition ? ifTrue : ifFalse</code>
 operators it contains.</p>
 <p>A single expression’s complexity should not become too high to keep the code readable.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <p>With the default threshold value of 3:</p>
 <pre>
 if (((condition1 &amp;&amp; condition2) || (condition3 &amp;&amp; condition4)) &amp;&amp; condition5) { ... }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 if ( (myFirstCondition() || mySecondCondition()) &amp;&amp; myLastCondition()) { ... }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>No issue is reported inside <code>equals</code> methods, because it is common to compare all the fields of a class for equality inside this kind of
 method.</p>
 

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

@@ -1,8 +1,9 @@
+<h2>Why is this an issue?</h2>
 <p>If a <code>private</code> field is declared but not used in the program, it can be considered dead code and should therefore be removed. This will
 improve maintainability because developers will not wonder what the variable is used for.</p>
 <p>Note that this rule does not take reflection into account, which means that issues will be raised on <code>private</code> fields that are only
 accessed using the reflection API.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 public class MyClass {
   private int foo = 42;
@@ -13,22 +14,19 @@ <h2>Noncompliant Code Example</h2>
 
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public class MyClass {
   public int compute(int a) {
     return a * 42;
   }
 }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>The rule admits 3 exceptions:</p>
 <ul>
   <li> Serialization id fields </li>
-  <li> Annotated fields </li>
-  <li> Fields from classes with native methods </li>
 </ul>
-<h3>Serialization id fields</h3>
 <p>The Java serialization runtime associates with each serializable class a version number, called <code>serialVersionUID</code>, which is used during
 deserialization to verify that the sender and receiver of a serialized object have loaded classes for that object that are compatible with respect to
 serialization.</p>
@@ -39,15 +37,19 @@ <h3>Serialization id fields</h3>
   private static final long serialVersionUID = 42L;
 }
 </pre>
-<h3>Annotated fields</h3>
+<ul>
+  <li> Annotated fields </li>
+</ul>
 <p>The unused field in this class will not be reported by the rule as it is annotated.</p>
 <pre>
 public class MyClass {
   @SomeAnnotation
   private int unused;
 }
 </pre>
-<h3>Fields from classes with native methods</h3>
+<ul>
+  <li> Fields from classes with native methods </li>
+</ul>
 <p>The unused field in this class will not be reported by the rule as it might be used by native code.</p>
 <pre>
 public class MyClass {

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

@@ -1,19 +1,20 @@
+<h2>Why is this an issue?</h2>
 <p>A long parameter list can indicate that a new structure should be created to wrap the numerous parameters or that the function is doing too many
 things.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <p>With a maximum number of 4 parameters:</p>
 <pre>
 public void doSomething(int param1, int param2, int param3, String param4, long param5) {
 ...
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public void doSomething(int param1, int param2, int param3, String param4) {
 ...
 }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>Methods annotated with :</p>
 <ul>
   <li> Spring’s <code>@RequestMapping</code> (and related shortcut annotations, like <code>@GetRequest</code>) </li>

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

@@ -1,10 +1,11 @@
+<h2>Why is this an issue?</h2>
 <p>Hard coding a URI makes it difficult to test a program: path literals are not always portable across operating systems, a given absolute path may
 not exist on a specific test environment, a specified Internet URL may not be available when executing the tests, production environment filesystems
 usually differ from the development environment, …​etc. For all those reasons, a URI should never be hard coded. Instead, it should be replaced by
 customizable parameter.</p>
 <p>Further even if the elements of a URI are obtained dynamically, portability can still be limited if the path-delimiters are hard-coded.</p>
 <p>This rule raises an issue when URI’s or path delimiters are hard coded.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 public class Foo {
   public Collection&lt;User&gt; listUsers() {
@@ -14,7 +15,7 @@ <h2>Noncompliant Code Example</h2>
   }
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public class Foo {
   // Configuration is a class that returns customizable properties: it can be mocked to be injected during tests.
@@ -32,7 +33,7 @@ <h2>Compliant Solution</h2>
   }
 }
 </pre>
-<h2>See</h2>
+<h2>Resources</h2>
 <ul>
   <li> <a href="https://wiki.sei.cmu.edu/confluence/x/OjdGBQ">CERT, MSC03-J.</a> - Never hard code sensitive information </li>
 </ul>

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

@@ -1,9 +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>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 for (int i = 0; i &lt; 42; i++){}  // Empty on purpose or missing piece of code ?
 </pre>
-<h2>Exceptions</h2>
+<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>
 

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

@@ -1,18 +1,19 @@
+<h2>Why is this an issue?</h2>
 <p>A magic number is a number that comes out of nowhere, and is directly used in a statement. Magic numbers are often used, for instance to limit the
 number of iterations of a loop, to test the value of a property, etc.</p>
 <p>Using magic numbers may seem obvious and straightforward when you’re writing a piece of code, but they are much less obvious and straightforward at
 debugging time.</p>
 <p>That is why magic numbers must be demystified by first being assigned to clearly named variables before being used.</p>
 <p>-1, 0 and 1 are not considered magic numbers.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 public static void doSomething() {
 	for(int i = 0; i &lt; 4; i++){                 // Noncompliant, 4 is a magic number
 		...
 	}
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public static final int NUMBER_OF_CYCLES = 4;
 public static void doSomething() {
@@ -21,6 +22,6 @@ <h2>Compliant Solution</h2>
   }
 }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>This rule ignores <code>hashCode</code> methods.</p>
 

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

@@ -1,3 +1,4 @@
+<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

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

@@ -1,11 +1,12 @@
+<h2>Why is this an issue?</h2>
 <p>Public class variable fields do not respect the encapsulation principle and has three main disadvantages:</p>
 <ul>
   <li> Additional behavior such as validation cannot be added. </li>
   <li> The internal representation is exposed, and cannot be changed afterwards. </li>
   <li> Member values are subject to change from anywhere in the code and may not meet the programmer’s assumptions. </li>
 </ul>
 <p>By using private attributes and accessor methods (set and get), unauthorized modifications are prevented.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 public class MyClass {
 
@@ -15,7 +16,7 @@ <h2>Noncompliant Code Example</h2>
 
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public class MyClass {
 
@@ -33,10 +34,10 @@ <h2>Compliant Solution</h2>
 
 }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>Because they are not modifiable, this rule ignores <code>public final</code> fields. Also, annotated fields, whatever the annotation(s) will be
 ignored, as annotations are often used by injection frameworks, which in exchange require having public fields.</p>
-<h2>See</h2>
+<h2>Resources</h2>
 <ul>
   <li> <a href="https://cwe.mitre.org/data/definitions/493">MITRE, CWE-493</a> - Critical Public Variable Without Final Modifier </li>
 </ul>

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

@@ -1,19 +1,20 @@
+<h2>Why is this an issue?</h2>
 <p>Shared naming conventions allow teams to collaborate effectively. This rule raises an issue when an open curly brace is not placed at the end of a
 line of code.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 if(condition)
 {
   doSomething();
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 if(condition) {
   doSomething();
 }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>When blocks are inlined (left and right curly braces on the same line), no issue is triggered.</p>
 <pre>
 if(condition) {doSomething();}

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

@@ -1,6 +1,7 @@
+<h2>Why is this an issue?</h2>
 <p>Shared coding conventions make it possible to collaborate efficiently. This rule makes it mandatory to place the open curly brace at the beginning
 of a line.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 public void myMethod {  // Noncompliant
   if(something) {  // Noncompliant
@@ -10,7 +11,7 @@ <h2>Noncompliant Code Example</h2>
   }
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public void myMethod
 {

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

@@ -1,7 +1,8 @@
+<h2>Why is this an issue?</h2>
 <p>Shared coding conventions make it possible for a team to collaborate efficiently.</p>
 <p>This rule makes it mandatory to place closing curly braces on the same line as the next <code>else</code>, <code>catch</code> or
 <code>finally</code> keywords.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 public void myMethod() {
   if(something) {
@@ -23,7 +24,7 @@ <h2>Noncompliant Code Example</h2>
   }
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public void myMethod() {
   if(something) {