From 5879d3546c82e1f720f4647e11f81ea01fee28cd Mon Sep 17 00:00:00 2001
From: Fred Tingaud
 <95592999+frederic-tingaud-sonarsource@users.noreply.github.com>
Date: Wed, 11 Oct 2023 16:34:18 +0200
Subject: [PATCH] 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    | 36 ++++++++++++++-------------
 rules/S878/compliant.adoc       |  7 ------
 rules/S878/description.adoc     |  1 -
 rules/S878/javascript/rule.adoc | 43 ++++++++++++++++++++++++---------
 rules/S878/noncompliant.adoc    |  6 -----
 5 files changed, 50 insertions(+), 43 deletions(-)
 delete mode 100644 rules/S878/compliant.adoc
 delete mode 100644 rules/S878/description.adoc
 delete mode 100644 rules/S878/noncompliant.adoc

diff --git a/rules/S878/cfamily/rule.adoc b/rules/S878/cfamily/rule.adoc
index cf7af6cf85..e9196e5ed4 100644
--- a/rules/S878/cfamily/rule.adoc
+++ b/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[]
 
 '''
diff --git a/rules/S878/compliant.adoc b/rules/S878/compliant.adoc
deleted file mode 100644
index 921e5024ee..0000000000
--- a/rules/S878/compliant.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-=== Compliant solution
-
-[source,text]
-----
-a +=  2;
-i = a + b;
-----
diff --git a/rules/S878/description.adoc b/rules/S878/description.adoc
deleted file mode 100644
index 319cc4d21d..0000000000
--- a/rules/S878/description.adoc
+++ /dev/null
@@ -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. 
diff --git a/rules/S878/javascript/rule.adoc b/rules/S878/javascript/rule.adoc
index f5b4d55a97..ba9bfda970 100644
--- a/rules/S878/javascript/rule.adoc
+++ b/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[]
 
 '''
diff --git a/rules/S878/noncompliant.adoc b/rules/S878/noncompliant.adoc
deleted file mode 100644
index db4f77e5cf..0000000000
--- a/rules/S878/noncompliant.adoc
+++ /dev/null
@@ -1,6 +0,0 @@
-=== Noncompliant code example
-
-[source,text]
-----
-i = a += 2, a + b;  // What's the value of i ?
-----