Modify S878: Migrate to LayC - comma operator

Co-authored-by: Marco Borgeaud <89914223+marco-antognini-sonarsource@users.noreply.github.com>
Co-authored-by: Yassin Kammoun <52890329+yassin-kammoun-sonarsource@users.noreply.github.com>

rules/S878/cfamily/rule.adoc

@@ -2,47 +2,49 @@
 
 The comma operator takes two expressions, executes them from left to right, and returns the result of the second one. The use of this operator is generally detrimental to the readability and reliability of code, and the same effect can be achieved by other means.
 
+[source,cpp]
+----
+i = a += 2, a + b;  // Noncompliant: What is the value of i?
+----
 
-It is especially error-prone in array subscripts where it might be misinterpreted as accessing a multidimensional array. The use of a comma in this context is deprecated since {cpp}20 (it might be repurposed in a later edition of the standard to actually access multidimensional arrays, but until then, it should really not be used).
-
-=== Noncompliant code example
+Writing each expression on its own line will improve readability and might fix misunderstandings.
 
 [source,cpp]
 ----
-i = a += 2, a + b;  // Noncompliant. What's the value of i ?
-
-a[1, 2] = 3; // Noncompliant: 1 is ignored. This is not an access to a multidimensional array.
-
-x = a[i++, j = i + 1, j*2]; // Noncompliant. What index is used for a?
+a += 2;
+i = a + b; // We probably expected to assign the result of the addition to i, although the previous code wasn't doing it.
 ----
 
-=== Compliant solution
+It is especially error-prone in array subscripts - until {cpp}20 - where it might be misinterpreted as accessing a multidimensional array.
 
 [source,cpp]
 ----
-a +=  2;
-i = a + b;
-
-j = i + 1;
-x = a[j*2];
-++i;
+a[1, 2] = 3; // Noncompliant: until C++20, 1 is ignored. This is not an access to a multidimensional array.
 ----
 
+Using a comma in this context was deprecated in {cpp}20, and a real multi-dimensional subscript operator was introduced in {cpp}23.
+
 === Exceptions
 
-Use of comma operator is tolerated in initialization and increment expressions of ``++for++`` loops.
+The comma operator is tolerated in initializations and increment expressions of `for` loops.
 
 [source,cpp]
 ----
-for(i = 0, j = 5; i < 6; i++, j++) { ... }
+for (i = 0, j = 5; i < 6; i++, j++) { ... }
 ----
 
 == Resources
 
+=== External coding guidelines
+
 * MISRA C:2004, 12.10 - The comma operator shall not be used.
 * MISRA {cpp}:2008, 5-18-1 - The comma operator shall not be used.
 * MISRA C:2012, 12.3 - The comma operator should not be used
 
+=== Documentation
+
+* {cpp} Reference - https://en.cppreference.com/w/cpp/language/operators#Array_subscript_operator[Array subscript operator]
+
 ifdef::env-github,rspecator-view[]
 
 '''

rules/S878/compliant.adoc

@@ -1,7 +0,0 @@
-=== Compliant solution
-
-[source,text]
-----
-a +=  2;
-i = a + b;
-----

rules/S878/description.adoc

@@ -1 +0,0 @@
-The comma operator takes two expressions, executes them from left to right and returns the result of the second one. Use of this operator is generally detrimental to the readability and reliability of code, and the same effect can be achieved by other means. 

rules/S878/javascript/rule.adoc

@@ -1,24 +1,43 @@
 == Why is this an issue?
 
-include::../description.adoc[]
-
-include::../noncompliant.adoc[]
-
-include::../compliant.adoc[]
-
-=== Exceptions
-
-Use of comma operator is tolerated:
-
-* in initialization and increment expressions of ``++for++`` loops.
+The comma operator takes two expressions, executes them from left to right, and returns the result of the second one. The use of this operator is generally detrimental to the readability and reliability of code, and the same effect can be achieved by other means. 
 
 [source,javascript]
 ----
-for(i = 0, j = 5; i < 6; i++, j++) { ... }
+i = a += 2, a + b;  // Noncompliant: What's the value of i ?
+----
+
+Writing each expression on its own line will improve readability and might fix misunderstandings.
+
+[source,javascript]
+----
+a += 2;
+i = a + b; // We probably expected to assign the result of the addition to i, although the previous code wasn't doing it.
+----
+
+=== Exceptions
+
+The comma operator is tolerated:
+
+* In initializations and increment expressions of ``++for++`` loops.
+
+[source,javascript]
+----
+for (i = 0, j = 5; i < 6; i++, j++) { ... }
 ----
 
 * If the expression sequence is explicitly wrapped in parentheses.
 
+[source,javascript]
+----
+i = (a += 2, a + b); // Compliant by exception
+----
+
+== Resources
+
+=== Documentation
+
+* MDN - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comma_operator[Comma operator (,)]
 ifdef::env-github,rspecator-view[]
 
 '''

rules/S878/noncompliant.adoc

@@ -1,6 +0,0 @@
-=== Noncompliant code example
-
-[source,text]
-----
-i = a += 2, a + b;  // What's the value of i ?
-----