Merge pull request #1588 from felicity-semmle/qhelp/SD-3447-commented-out-code

calumgrant · web-flow · commit 87a43718e91e · 2019-07-16T09:38:33.000+01:00
Update Python and C# help for commented-out code to use common qhelp
diff --git a/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.qhelp b/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.qhelp
@@ -2,23 +2,6 @@
   "-//Semmle//qhelp//EN"
   "qhelp.dtd">
 <qhelp>
-<overview>
-<p>
-Commented-out code is distracting and confusing for developers who read the surrounding code,
-and its significance is often unclear. It should therefore be avoided.
-</p>
-
-</overview>
-<recommendation>
-
-<p>
-Remove the commented-out code, or reinstate it if necessary.
-</p>
-
-</recommendation>
-<references>
-
-<li>High Integrity C++ Coding Standard: <a href="http://www.codingstandard.com/rule/2-3-2-do-not-comment-out-code/">2.3.2 Do not comment out code</a>.</li>
-
-</references>
+  <include src="CommentedOutCodeQuery.qhelp" />
+  <include src="CommentedOutCodeReferences.qhelp" />
 </qhelp>
diff --git a/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.ql b/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.ql
@@ -1,6 +1,6 @@
 /**
  * @name Commented-out code
- * @description Comments that contain commented-out code should be avoided.
+ * @description Commented-out code makes the remaining code more difficult to read.
  * @kind problem
  * @problem.severity recommendation
  * @precision medium
diff --git a/python/ql/src/Lexical/CommentedOutCode.qhelp b/python/ql/src/Lexical/CommentedOutCode.qhelp
@@ -3,5 +3,6 @@
   "qhelp.dtd">
 <qhelp>
   <include src="CommentedOutCodeQuery.qhelp" />
-  <include src="CommentedOutCodeCommon.qhelp" />
+  <include src="CommentedOutCodeExample.qhelp" />
+  <include src="CommentedOutCodeReferences.qhelp" />
 </qhelp>
diff --git a/python/ql/src/Lexical/CommentedOutCode.ql b/python/ql/src/Lexical/CommentedOutCode.ql
@@ -1,6 +1,6 @@
 /**
- * @name Commented out code
- * @description Commented out code causes visual clutter as it is neither code nor comment.
+ * @name Commented-out code
+ * @description Commented-out code makes the remaining code more difficult to read.
  * @kind problem
  * @tags maintainability
  *       readability
diff --git a/python/ql/src/Lexical/CommentedOutCodeCommon.qhelp b/python/ql/src/Lexical/CommentedOutCodeCommon.qhelp
diff --git a/python/ql/src/Lexical/CommentedOutCodeExample.qhelp b/python/ql/src/Lexical/CommentedOutCodeExample.qhelp
@@ -0,0 +1,16 @@
+<!DOCTYPE qhelp PUBLIC
+  "-//Semmle//qhelp//EN"
+  "qhelp.dtd">
+<qhelp>
+
+<example>
+<p>
+In the following example, a <code>print</code> statement, originally used
+for debugging, is left in the code, but commented out. It should be removed altogether.
+</p>
+
+<sample src="CommentedOutCode.py" />
+
+</example>
+
+</qhelp>
