SONARFLEX-187 Update rule metadata (#197)

Author: yassin-kammoun-sonarsource

flex-checks/src/main/resources/org/sonar/l10n/flex/rules/flex/CommentedCode.html

@@ -1,4 +1,5 @@
 <h2>Why is this an issue?</h2>
-<p>Programmers should not comment out code as it bloats programs and reduces readability.</p>
-<p>Unused code should be deleted and can be retrieved from source control history if required.</p>
+<p>Commented-out code distracts the focus from the actual executed code. It creates a noise that increases maintenance code. And because it is never
+executed, it quickly becomes out of date and invalid.</p>
+<p>Commented-out code should be deleted and can be retrieved from source control history if required.</p>
 

flex-checks/src/main/resources/org/sonar/l10n/flex/rules/flex/NonEmptyCaseWithoutBreak.html

@@ -48,6 +48,6 @@ <h3>Exceptions</h3>
 </pre>
 <h2>Resources</h2>
 <ul>
-  <li> <a href="https://cwe.mitre.org/data/definitions/484">MITRE, CWE-484</a> - Omitted Break Statement in Switch </li>
+  <li> CWE - <a href="https://cwe.mitre.org/data/definitions/484">CWE-484 - Omitted Break Statement in Switch</a> </li>
 </ul>
 

flex-checks/src/main/resources/org/sonar/l10n/flex/rules/flex/NonEmptyCaseWithoutBreak.json

@@ -3,7 +3,7 @@
   "type": "CODE_SMELL",
   "code": {
     "impacts": {
-      "MAINTAINABILITY": "HIGH"
+      "MAINTAINABILITY": "BLOCKER"
     },
     "attribute": "CLEAR"
   },

flex-checks/src/main/resources/org/sonar/l10n/flex/rules/flex/ParsingError.json

@@ -13,5 +13,5 @@
   "ruleSpecification": "RSPEC-2260",
   "sqKey": "S2260",
   "scope": "All",
-  "quickfix": "unknown"
+  "quickfix": "infeasible"
 }

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

@@ -1,14 +1,16 @@
 <h2>Why is this an issue?</h2>
-<p>Merging collapsible <code>if</code> statements increases the code’s readability.</p>
-<h3>Noncompliant code example</h3>
+<p>Nested code - blocks of code inside blocks of code - is eventually necessary, but increases complexity. This is why keeping the code as flat as
+possible, by avoiding unnecessary nesting, is considered a good practice.</p>
+<p>Merging <code>if</code> statements when possible will decrease the nesting of the code and improve its readability.</p>
+<p>Code like</p>
 <pre>
 if (condition1) {
-  if (condition2) {             // NonCompliant
+  if (condition2) {             // Noncompliant
     ...
   }
 }
 </pre>
-<h3>Compliant solution</h3>
+<p>Is more readable as</p>
 <pre>
 if (condition1 &amp;&amp; condition2) {
   ...

flex-checks/src/main/resources/org/sonar/l10n/flex/rules/flex/S1066.json

@@ -1,5 +1,5 @@
 {
-  "title": "Collapsible \"if\" statements should be merged",
+  "title": "Mergeable \"if\" statements should be combined",
   "type": "CODE_SMELL",
   "code": {
     "impacts": {

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

@@ -1,19 +1,10 @@
 <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>
-<h3>Noncompliant code example</h3>
-<pre>
-public class MyClass {
-  private var foo:int = 4;                       //foo is unused
-
-  public function compute(a:int):int{
-    return a * 4;
-  }
-}
-</pre>
-<h3>Compliant solution</h3>
+<p>If a <code>private</code> field is declared but not used locally, its limited visibility makes it dead code.</p>
+<p>This is either a sign that some logic is missing or that the code should be cleaned.</p>
+<p>Cleaning out dead code decreases the size of the maintained codebase, making it easier to understand and preventing bugs from being introduced.</p>
 <pre>
 public class MyClass {
+  private var foo:int = 4;  // Noncompliant: foo is unused and should be removed
 
   public function compute(a:int):int{
     return a * 4;

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

@@ -1,5 +1,5 @@
 <h2>Why is this an issue?</h2>
-<p>Functions with a long parameter list are difficult to use, as maintainers must figure out the role of each parameter and keep track of their
+<p>Functions with a long parameter list are difficult to use because maintainers must figure out the role of each parameter and keep track of their
 position.</p>
 <pre>
 function setCoordinates(var x1, var y1, var z1, var x2, var y2, var z2) { // Noncompliant

flex-checks/src/main/resources/org/sonar/l10n/flex/rules/flex/S1116.html

@@ -1,9 +1,7 @@
 <h2>Why is this an issue?</h2>
-<p>Empty statements, i.e. <code>;</code>, are usually introduced by mistake, for example because:</p>
-<ul>
-  <li> It was meant to be replaced by an actual statement, but this was forgotten. </li>
-  <li> There was a typo which lead the semicolon to be doubled, i.e. <code>;;</code>. </li>
-</ul>
+<p>Empty statements represented by a semicolon <code>;</code> are statements that do not perform any operation. They are often the result of a typo or
+a misunderstanding of the language syntax. It is a good practice to remove empty statements since they don’t add value and lead to confusion and
+errors.</p>
 <h3>Noncompliant code example</h3>
 <pre>
 function doSomething():void {

flex-checks/src/main/resources/org/sonar/l10n/flex/rules/flex/S1117.html

@@ -1,13 +1,23 @@
 <h2>Why is this an issue?</h2>
-<p>Overriding or shadowing a variable declared in an outer scope can strongly impact the readability, and therefore the maintainability, of a piece of
-code. Further, it could lead maintainers to introduce bugs because they think they’re using one variable but are really using another.</p>
+<p>Shadowing occurs when a local variable has the same name as a variable or a field in an outer scope.</p>
+<p>This can lead to three main problems:</p>
+<ul>
+  <li> Confusion: The same name can refer to different variables in different parts of the scope, making the code hard to read and understand. </li>
+  <li> Unintended Behavior: You might accidentally use the wrong variable, leading to hard-to-detect bugs. </li>
+  <li> Maintenance Issues: If the inner variable is removed or renamed, the code’s behavior might change unexpectedly because the outer variable is
+  now being used. </li>
+</ul>
+<p>To avoid these problems, rename the shadowing, shadowed, or both identifiers to accurately represent their purpose with unique and meaningful
+names.</p>
+<p>This rule focuses on variables in methods that shadow a field.</p>
+<h3>Noncompliant code example</h3>
 <pre>
 class Foo {
   public var myField:int;
 
   public function doSomething():String {
-    var myField:int = 0; /* Noncompliant */
-    ...
+    var myField:int = 0; // Noncompliant
+    //...
   }
 }
 </pre>