hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-04-30 19:26:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Update Python and C# help for commented-out code to use common qhelp
This commit is contained in:
Calum Grant
2019-07-16 09:38:33 +01:00
committed by GitHub
parent 48842c8fb5 cb48af7395
commit 87a43718e9
6 changed files with 23 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
csharp/ql/src/Bad Practices/Comments/CommentedOutCode.qhelp
View File

@@ -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>

2
csharp/ql/src/Bad Practices/Comments/CommentedOutCode.ql
View File

@@ -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

3
python/ql/src/Lexical/CommentedOutCode.qhelp
View File

@@ -3,5 +3,6 @@
"qhelp.dtd">
<qhelp>
<include src="CommentedOutCodeQuery.qhelp" />
<include src="CommentedOutCodeCommon.qhelp" />
<include src="CommentedOutCodeExample.qhelp" />
<include src="CommentedOutCodeReferences.qhelp" />
</qhelp>

4
python/ql/src/Lexical/CommentedOutCode.ql
View File

@@ -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

28
python/ql/src/Lexical/CommentedOutCodeCommon.qhelp
View File

@@ -1,28 +0,0 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<recommendation>
<p>
Remove the commented-out code, or reinstate it if necessary. If you want to include a snippet
of example code in a comment, consider adding an <code>@example</code> tag or enclosing the code
in a <code>code</code> or <code>pre</code> element.
</p>
</recommendation>
<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>
<references>
<li>Los Techies: <a href="http://lostechies.com/rodpaddock/2010/12/29/commented-code-technical-debt">Commented Code == Technical Debt</a>.</li>
</references>
</qhelp>

16
python/ql/src/Lexical/CommentedOutCodeExample.qhelp Normal file
View File

@@ -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>