Apply suggestions from code review

Co-authored-by: Felicity Chapman <[email protected]>
Co-authored-by: Geoffrey White <[email protected]>

Author: 3 people

cpp/ql/src/Best Practices/Likely Errors/CommaBeforeMisleadingIndentation.cpp

@@ -1,5 +1,5 @@
 /*
- * Here, the comma should have been a semicolon:
+ * In this example, the developer intended to use a semicolon but accidentally used a comma:
  */
 
 enum privileges entitlements = NONE;
@@ -10,7 +10,7 @@ if (is_admin)
 restrict_privileges(entitlements);
 
 /*
- * This is misleading, because the code is unexpectedly equivalent to:
+ * The use of a comma means that the first example is equivalent to this second example:
  */
 
 enum privileges entitlements = NONE;
@@ -21,7 +21,7 @@ if (is_admin) {
 }
 
 /*
- * Whereas the following code was probably intended:
+ * The indentation of the first example suggests that the developer probably intended the following code:
  */
 
 enum privileges entitlements = NONE;

cpp/ql/src/Best Practices/Likely Errors/CommaBeforeMisleadingIndentation.qhelp

@@ -5,26 +5,29 @@
 
 <overview>
 <p>
-If the expression to the right of a comma operator starts at an earlier column than the expression to the left, then
+If the expression after the comma operator starts at an earlier column than the expression before the comma, then
 this suspicious indentation possibly indicates a logic error, caused by a typo that may escape visual inspection.
 </p>
 <warning>
 This query has medium precision because CodeQL currently does not distinguish between tabs and spaces in whitespace.
-Alerts may therefore flag code that appears readable for one value of tab size but not another.
+If a file contains mixed tabs and spaces, alerts may highlight code that is correctly indented for one value of tab size but not for other tab sizes.
 </warning>
 </overview>
 
 <recommendation>
 <p>
-Use standard indentation around the comma operator: begin the right-hand-side operand at the same level of
-indentation (column number) as the left-hand-side operand.
+To ensure that your code is easy to read and review, use standard indentation around the comma operator. Always begin the right-hand-side operand at the same level of
+indentation (column number) as the left-hand-side operand. This makes it easier for other developers to see the intended behavior of your code.
 </p>
 <p>
-When it comes to whitespace, either do not mix tabs and spaces, or mix them consistently.
+Use whitespace consistently to communicate your coding intentions. Where possible, avoid mixing tabs and spaces within a file. If you need to mix them, use them consistently.
 </p>
 </recommendation>
 
 <example>
+<p>
+This example shows three different ways of writing the same code. The first example contains a comma instead of a semicolon which means that the final line is part of the <code>if</code> statement, even though the indentation suggests that it is intended to be separate. The second example looks different put is functionally the same as the first example. It is more likely that the developer intended to write the third example.
+</p>
 <sample src="CommaBeforeMisleadingIndentation.cpp" />
 </example>
 

cpp/ql/src/Best Practices/Likely Errors/CommaBeforeMisleadingIndentation.ql

@@ -1,6 +1,6 @@
 /**
  * @name Comma before misleading indentation
- * @description The expressions before and after the comma operator can be misread because of an unusual difference in start columns.
+ * @description If expressions before and after a comma operator use different indentation, it is easy to misread the purpose of the code.
  * @kind problem
  * @id cpp/comma-before-misleading-indentation
  * @problem.severity warning