hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2025-12-16 16:53:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4176 from aibaars/missing-qhelp

Browse Source 
Add missing QHelp files
This commit is contained in:
Arthur Baars
2020-09-02 16:12:42 +02:00
committed by GitHub
parent 2c0e9f0c86 aedfa47cb4
commit 90f013d74f
50 changed files with 754 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
config/identical-files.json
View File

@@ -335,5 +335,50 @@
"java/ql/src/semmle/code/xml/XML.qll",
"javascript/ql/src/semmle/javascript/XML.qll",
"python/ql/src/semmle/python/xml/XML.qll"
],
"DuplicationProblems.qhelp": [
"cpp/ql/src/Metrics/Files/DuplicationProblems.qhelp",
"csharp/ql/src/Metrics/Files/DuplicationProblems.qhelp",
"javascript/ql/src/Metrics/DuplicationProblems.qhelp",
"python/ql/src/Metrics/DuplicationProblems.qhelp"
],
"CommentedOutCodeQuery.qhelp": [
"cpp/ql/src/Documentation/CommentedOutCodeQuery.qhelp",
"python/ql/src/Lexical/CommentedOutCodeQuery.qhelp",
"csharp/ql/src/Bad Practices/Comments/CommentedOutCodeQuery.qhelp",
"java/ql/src/Violations of Best Practice/Comments/CommentedOutCodeQuery.qhelp",
"javascript/ql/src/Comments/CommentedOutCodeQuery.qhelp"
],
"FLinesOfCodeReferences.qhelp": [
"java/ql/src/Metrics/Files/FLinesOfCodeReferences.qhelp",
"javascript/ql/src/Metrics/FLinesOfCodeReferences.qhelp"
],
"FCommentRatioCommon.qhelp": [
"java/ql/src/Metrics/Files/FCommentRatioCommon.qhelp",
"javascript/ql/src/Metrics/FCommentRatioCommon.qhelp"
],
"FLinesOfCodeOverview.qhelp": [
"java/ql/src/Metrics/Files/FLinesOfCodeOverview.qhelp",
"javascript/ql/src/Metrics/FLinesOfCodeOverview.qhelp"
],
"CommentedOutCodeMetricOverview.qhelp": [
"cpp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp",
"csharp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp",
"java/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp",
"javascript/ql/src/Comments/CommentedOutCodeMetricOverview.qhelp",
"python/ql/src/Lexical/CommentedOutCodeMetricOverview.qhelp"
],
"FLinesOfDuplicatedCodeCommon.qhelp": [
"cpp/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp",
"java/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp",
"javascript/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp",
"python/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp"
],
"CommentedOutCodeReferences.qhelp": [
"cpp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp",
"csharp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp",
"java/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp",
"javascript/ql/src/Comments/CommentedOutCodeReferences.qhelp",
"python/ql/src/Lexical/CommentedOutCodeReferences.qhelp"
]
}

11
cpp/ql/src/Critical/aliasAnalysisWarning.qhelp Normal file
View File

@@ -0,0 +1,11 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<fragment>
<warning>
This check is an approximation, so some results may not be actual defects in the program.
It is not possible in general to compute the exact value of the variable without running the program with all possible input data.
</warning>
</fragment>
</qhelp>

12
cpp/ql/src/Critical/callGraphWarning.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<fragment>
<warning>
This check is an approximation, so some results may not be actual defects in the program.
It is not possible in general to compute which function is actually called in a virtual call,
or a call through a pointer, without running the program with all possible input data.
</warning>
</fragment>
</qhelp>

13
cpp/ql/src/Critical/dataFlowWarning.qhelp Normal file
View File

@@ -0,0 +1,13 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<fragment>
<warning>
This check is an approximation, so some results may not be actual defects in the program.
It is not possible in general to compute the actual branch taken in conditional statements such
as "if" without running the program with all possible input data. This means that it is not possible
to determine if a particular statement is going to be executed.
</warning>
</fragment>
</qhelp>

11
cpp/ql/src/Critical/pointsToWarning.qhelp Normal file
View File

@@ -0,0 +1,11 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<fragment>
<warning>
This check is an approximation, so some results may not be actual defects in the program. It is not possible
in general to compute the values of pointers without running the program with all input data.
</warning>
</fragment>
</qhelp>

2
cpp/ql/src/Documentation/CommentedOutCode.qhelp
View File

@@ -3,5 +3,5 @@
"qhelp.dtd">
<qhelp>
<include src="CommentedOutCodeQuery.qhelp" />
<include src="CommentedOutCodeReferences.qhelp" />
<include src="../Metrics/Files/CommentedOutCodeReferences.qhelp" />
</qhelp>

25
cpp/ql/src/Documentation/CommentedOutCodeQuery.qhelp Normal file
View File

@@ -0,0 +1,25 @@
<!DOCTYPE qhelp PUBLIC
"-//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 will not get compiled or tested when the code around
it changes, so it's likely to break over time. For these reasons, commented-out code should be
avoided.
</p>
</overview>
<recommendation>
<p>
Remove or reinstate the commented-out code. If you want to include a snippet of example code
in a comment, consider enclosing it in quotes or marking it up as appropriate for the source
language.
</p>
</recommendation>
</qhelp>

12
cpp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric counts the number of lines of commented-out code in each file. Large amounts of
commented-out code often indicate poorly maintained code.
</p>
</overview>
</qhelp>

12
cpp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<references>
<li>Mark Needham: <a href="http://www.markhneedham.com/blog/2009/01/17/the-danger-of-commenting-out-code/">The danger of commenting out code</a>.</li>
<li>Los Techies: <a href="http://lostechies.com/rodpaddock/2010/12/29/commented-code-technical-debt">Commented Code == Technical Debt</a>.</li>
<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>
</qhelp>

16
cpp/ql/src/Metrics/Files/DuplicationProblems.qhelp Normal file
View File

@@ -0,0 +1,16 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
Duplicated code increases overall code size, making the code base
harder to maintain and harder to understand. It also becomes harder to fix bugs,
since a programmer applying a fix to one copy has to always remember to update
other copies accordingly. Finally, code duplication is generally an indication of
a poorly designed or hastily written code base, which typically suffers from other
problems as well.
</p>
</overview>
</qhelp>

35
cpp/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp Normal file
View File

@@ -0,0 +1,35 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file.
</p>
<p>
A file that contains many lines that are duplicated within the code base is problematic
for a number of reasons.
</p>
</overview>
<include src="DuplicationProblems.qhelp" />
<recommendation>
<p>
Refactor files with lots of duplicated code to extract the common code into
a shared library or module.
</p>
</recommendation>
<references>
<li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Duplicate_code">Duplicate code</a>.</li>
<li>M. Fowler, <em>Refactoring</em>. Addison-Wesley, 1999.</li>
</references>
</qhelp>

2
cpp/ql/src/jsf/4.05 Libraries/AV Rule 24.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query highlights calls to the standard library functions <code>abort, exit, getenv</code> and <code>system</code>.

2
cpp/ql/src/jsf/4.10 Classes/AV Rule 85.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query ensures that all operators with opposites (e.g. == and !=) are both defined, and

4
cpp/ql/src/jsf/4.13 Functions/AV Rule 111.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query highlights return statements that return pointers to an object allocated on the stack. The lifetime
@@ -18,7 +18,7 @@ memory after the function has already returned will have undefined results.
<!-- Mention how the results could be probabilistic (uses pointsto) -->
<include src="pointsToWarning.qhelp" />
<include src="../../Critical/pointsToWarning.qhelp" />
</overview>
<recommendation>

2
cpp/ql/src/jsf/4.13 Functions/AV Rule 114.qhelp
View File

@@ -12,7 +12,7 @@ calling convention for x86, it would be whatever value was in the AX/EAX registe
assuming the function had a non-float return type that can fit in a machine word.
</p>
<include src="dataFlowWarning.qhelp" />
<include src="../../Critical/dataFlowWarning.qhelp" />
<!--/*FALSEPOSITIVE_WARNING*/-->

2
cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 135.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query highlights identifiers in an inner scope that hide (have the same name as) an identifier in an outer scope.

2
cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 140.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query highlights variables with the <code>register</code> storage class specifier. Modern compilers are now capable of

2
cpp/ql/src/jsf/4.17 Types/AV Rule 147.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query highlights portions of code that can expose the floating point implementation of the underlying

2
cpp/ql/src/jsf/4.18 Constants/AV Rule 151.1.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query highlights string literals that are assigned to a non-<code>const</code> variable. String literals

2
cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 154.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query finds bit fields with members that are not explicitly declared to be unsigned.

2
cpp/ql/src/jsf/4.21 Operators/AV Rule 165.qhelp
View File

@@ -7,7 +7,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>
This query finds unsigned values that are being negated. Behavior is undefined in such cases.

2
cpp/ql/src/jsf/4.24 Control Flow Structures/AV Rule 189.qhelp
View File

@@ -6,7 +6,7 @@
<overview>
<!-- Mention that this rule may not be applicable in projects that don't follow the JSF standard. -->
<include src="cpp/jsfNote.qhelp" />
<include src="../jsfNote.qhelp" />
<p>Use of goto statements makes code more difficult to understand and maintain. Consequently, the use
of goto statements is deprecated except as a mechanism for breaking out of multiple nested loops.

18
cpp/ql/src/jsf/jsfNote.qhelp Normal file
View File

@@ -0,0 +1,18 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<fragment>
<p>
This query is part of a suite that tests code against
the <em>Joint Strike Fighter Air Vehicle C++ Coding Standard</em> (JSF).
Alerts reported by this query highlight code that may break the
JSF rule listed in the References section.
</p>
<p>
The JSF rule this query tests is likely to be too strict for projects
that do not follow the JSF standard.
</p>
</fragment>
</qhelp>

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

@@ -3,5 +3,5 @@
"qhelp.dtd">
<qhelp>
<include src="CommentedOutCodeQuery.qhelp" />
<include src="CommentedOutCodeReferences.qhelp" />
<include src="../../Metrics/Files/CommentedOutCodeReferences.qhelp" />
</qhelp>

25
csharp/ql/src/Bad Practices/Comments/CommentedOutCodeQuery.qhelp Normal file
View File

@@ -0,0 +1,25 @@
<!DOCTYPE qhelp PUBLIC
"-//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 will not get compiled or tested when the code around
it changes, so it's likely to break over time. For these reasons, commented-out code should be
avoided.
</p>
</overview>
<recommendation>
<p>
Remove or reinstate the commented-out code. If you want to include a snippet of example code
in a comment, consider enclosing it in quotes or marking it up as appropriate for the source
language.
</p>
</recommendation>
</qhelp>

12
csharp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric counts the number of lines of commented-out code in each file. Large amounts of
commented-out code often indicate poorly maintained code.
</p>
</overview>
</qhelp>

12
csharp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<references>
<li>Mark Needham: <a href="http://www.markhneedham.com/blog/2009/01/17/the-danger-of-commenting-out-code/">The danger of commenting out code</a>.</li>
<li>Los Techies: <a href="http://lostechies.com/rodpaddock/2010/12/29/commented-code-technical-debt">Commented Code == Technical Debt</a>.</li>
<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>
</qhelp>

16
csharp/ql/src/Metrics/Files/DuplicationProblems.qhelp Normal file
View File

@@ -0,0 +1,16 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
Duplicated code increases overall code size, making the code base
harder to maintain and harder to understand. It also becomes harder to fix bugs,
since a programmer applying a fix to one copy has to always remember to update
other copies accordingly. Finally, code duplication is generally an indication of
a poorly designed or hastily written code base, which typically suffers from other
problems as well.
</p>
</overview>
</qhelp>

12
java/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric counts the number of lines of commented-out code in each file. Large amounts of
commented-out code often indicate poorly maintained code.
</p>
</overview>
</qhelp>

12
java/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<references>
<li>Mark Needham: <a href="http://www.markhneedham.com/blog/2009/01/17/the-danger-of-commenting-out-code/">The danger of commenting out code</a>.</li>
<li>Los Techies: <a href="http://lostechies.com/rodpaddock/2010/12/29/commented-code-technical-debt">Commented Code == Technical Debt</a>.</li>
<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>
</qhelp>

38
java/ql/src/Metrics/Files/FCommentRatioCommon.qhelp Normal file
View File

@@ -0,0 +1,38 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric measures the percentage of a file's lines that are comment rather
than code.
</p>
<p>
A low percentage of comments in a file may indicate either a potentially
worrying lack of documentation or that the file was generated by an automated
tool. A quick visual inspection should be sufficient to distinguish between
the two cases.
</p>
</overview>
<recommendation>
<p>
Files that were not auto-generated and have a low comment percentage should
be documented more fully. Refer to [McConnell] for more on how to write good
comments.
</p>
</recommendation>
<references>
<li>
S. McConnell. <em>Code Complete</em>, 2nd Edition. Microsoft Press, 2004.
</li>
</references>
</qhelp>

32
java/ql/src/Metrics/Files/FLinesOfCodeOverview.qhelp Normal file
View File

@@ -0,0 +1,32 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<fragment>
<p>
There are a number of problems associated with a high number of lines of code:
</p>
<ul>
<li>
It can be difficult to understand and maintain, even with good tool support.
</li>
<li>
It increases the likelihood of multiple developers needing to work on the same
file at once, and it therefore increases the likelihood of merge conflicts.
</li>
<li>
It may increase network traffic if you use a version control system that requires the whole file to
be transmitted even for a tiny change.
</li>
<li>
It may arise as a result of bundling many unrelated things into the
same file, and so it can indicate weak code organization.
</li>
</ul>
</fragment>
</qhelp>

10
java/ql/src/Metrics/Files/FLinesOfCodeReferences.qhelp Normal file
View File

@@ -0,0 +1,10 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<references>
<li>
M. Fowler, <em>Refactoring</em>. Addison-Wesley, 1999.
</li>
</references>
</qhelp>

35
java/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp Normal file
View File

@@ -0,0 +1,35 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file.
</p>
<p>
A file that contains many lines that are duplicated within the code base is problematic
for a number of reasons.
</p>
</overview>
<include src="DuplicationProblems.qhelp" />
<recommendation>
<p>
Refactor files with lots of duplicated code to extract the common code into
a shared library or module.
</p>
</recommendation>
<references>
<li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Duplicate_code">Duplicate code</a>.</li>
<li>M. Fowler, <em>Refactoring</em>. Addison-Wesley, 1999.</li>
</references>
</qhelp>

2
java/ql/src/Violations of Best Practice/Comments/CommentedCode.qhelp
View File

@@ -3,5 +3,5 @@
"qhelp.dtd">
<qhelp>
<include src="CommentedOutCodeQuery.qhelp" />
<include src="CommentedOutCodeReferences.qhelp" />
<include src="../../Metrics/Files/CommentedOutCodeReferences.qhelp" />
</qhelp>

25
java/ql/src/Violations of Best Practice/Comments/CommentedOutCodeQuery.qhelp Normal file
View File

@@ -0,0 +1,25 @@
<!DOCTYPE qhelp PUBLIC
"-//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 will not get compiled or tested when the code around
it changes, so it's likely to break over time. For these reasons, commented-out code should be
avoided.
</p>
</overview>
<recommendation>
<p>
Remove or reinstate the commented-out code. If you want to include a snippet of example code
in a comment, consider enclosing it in quotes or marking it up as appropriate for the source
language.
</p>
</recommendation>
</qhelp>

12
javascript/ql/src/Comments/CommentedOutCodeMetricOverview.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric counts the number of lines of commented-out code in each file. Large amounts of
commented-out code often indicate poorly maintained code.
</p>
</overview>
</qhelp>

25
javascript/ql/src/Comments/CommentedOutCodeQuery.qhelp Normal file
View File

@@ -0,0 +1,25 @@
<!DOCTYPE qhelp PUBLIC
"-//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 will not get compiled or tested when the code around
it changes, so it's likely to break over time. For these reasons, commented-out code should be
avoided.
</p>
</overview>
<recommendation>
<p>
Remove or reinstate the commented-out code. If you want to include a snippet of example code
in a comment, consider enclosing it in quotes or marking it up as appropriate for the source
language.
</p>
</recommendation>
</qhelp>

12
javascript/ql/src/Comments/CommentedOutCodeReferences.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<references>
<li>Mark Needham: <a href="http://www.markhneedham.com/blog/2009/01/17/the-danger-of-commenting-out-code/">The danger of commenting out code</a>.</li>
<li>Los Techies: <a href="http://lostechies.com/rodpaddock/2010/12/29/commented-code-technical-debt">Commented Code == Technical Debt</a>.</li>
<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>
</qhelp>

16
javascript/ql/src/Metrics/DuplicationProblems.qhelp Normal file
View File

@@ -0,0 +1,16 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
Duplicated code increases overall code size, making the code base
harder to maintain and harder to understand. It also becomes harder to fix bugs,
since a programmer applying a fix to one copy has to always remember to update
other copies accordingly. Finally, code duplication is generally an indication of
a poorly designed or hastily written code base, which typically suffers from other
problems as well.
</p>
</overview>
</qhelp>

38
javascript/ql/src/Metrics/FCommentRatioCommon.qhelp Normal file
View File

@@ -0,0 +1,38 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric measures the percentage of a file's lines that are comment rather
than code.
</p>
<p>
A low percentage of comments in a file may indicate either a potentially
worrying lack of documentation or that the file was generated by an automated
tool. A quick visual inspection should be sufficient to distinguish between
the two cases.
</p>
</overview>
<recommendation>
<p>
Files that were not auto-generated and have a low comment percentage should
be documented more fully. Refer to [McConnell] for more on how to write good
comments.
</p>
</recommendation>
<references>
<li>
S. McConnell. <em>Code Complete</em>, 2nd Edition. Microsoft Press, 2004.
</li>
</references>
</qhelp>

32
javascript/ql/src/Metrics/FLinesOfCodeOverview.qhelp Normal file
View File

@@ -0,0 +1,32 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<fragment>
<p>
There are a number of problems associated with a high number of lines of code:
</p>
<ul>
<li>
It can be difficult to understand and maintain, even with good tool support.
</li>
<li>
It increases the likelihood of multiple developers needing to work on the same
file at once, and it therefore increases the likelihood of merge conflicts.
</li>
<li>
It may increase network traffic if you use a version control system that requires the whole file to
be transmitted even for a tiny change.
</li>
<li>
It may arise as a result of bundling many unrelated things into the
same file, and so it can indicate weak code organization.
</li>
</ul>
</fragment>
</qhelp>

10
javascript/ql/src/Metrics/FLinesOfCodeReferences.qhelp Normal file
View File

@@ -0,0 +1,10 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<references>
<li>
M. Fowler, <em>Refactoring</em>. Addison-Wesley, 1999.
</li>
</references>
</qhelp>

35
javascript/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp Normal file
View File

@@ -0,0 +1,35 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file.
</p>
<p>
A file that contains many lines that are duplicated within the code base is problematic
for a number of reasons.
</p>
</overview>
<include src="DuplicationProblems.qhelp" />
<recommendation>
<p>
Refactor files with lots of duplicated code to extract the common code into
a shared library or module.
</p>
</recommendation>
<references>
<li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Duplicate_code">Duplicate code</a>.</li>
<li>M. Fowler, <em>Refactoring</em>. Addison-Wesley, 1999.</li>
</references>
</qhelp>

36
javascript/ql/src/Metrics/FLinesOfSimilarCodeCommon.qhelp Normal file
View File

@@ -0,0 +1,36 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file.
</p>
<p>
A file that contains many lines that are similar to other code within the code base is
problematic for the same reasons as a file that contains a lot of (exactly)
duplicated code.
</p>
</overview>
<include src="DuplicationProblems.qhelp" />
<recommendation>
<p>
Refactor similar code snippets by extracting common functionality into functions
that can be reused across modules.
</p>
</recommendation>
<references>
<li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Duplicate_code">Duplicate code</a>.</li>
<li>M. Fowler, <em>Refactoring</em>. Addison-Wesley, 1999.</li>
</references>
</qhelp>

12
python/ql/src/Lexical/CommentedOutCodeMetricOverview.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric counts the number of lines of commented-out code in each file. Large amounts of
commented-out code often indicate poorly maintained code.
</p>
</overview>
</qhelp>

25
python/ql/src/Lexical/CommentedOutCodeQuery.qhelp Normal file
View File

@@ -0,0 +1,25 @@
<!DOCTYPE qhelp PUBLIC
"-//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 will not get compiled or tested when the code around
it changes, so it's likely to break over time. For these reasons, commented-out code should be
avoided.
</p>
</overview>
<recommendation>
<p>
Remove or reinstate the commented-out code. If you want to include a snippet of example code
in a comment, consider enclosing it in quotes or marking it up as appropriate for the source
language.
</p>
</recommendation>
</qhelp>

12
python/ql/src/Lexical/CommentedOutCodeReferences.qhelp Normal file
View File

@@ -0,0 +1,12 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<references>
<li>Mark Needham: <a href="http://www.markhneedham.com/blog/2009/01/17/the-danger-of-commenting-out-code/">The danger of commenting out code</a>.</li>
<li>Los Techies: <a href="http://lostechies.com/rodpaddock/2010/12/29/commented-code-technical-debt">Commented Code == Technical Debt</a>.</li>
<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>
</qhelp>

1
python/ql/src/Metrics/DuplicationProblems.qhelp
View File

@@ -12,6 +12,5 @@ a poorly designed or hastily written code base, which typically suffers from oth
problems as well.
</p>
</overview>
</qhelp>

35
python/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp Normal file
View File

@@ -0,0 +1,35 @@
<!DOCTYPE qhelp PUBLIC
"-//Semmle//qhelp//EN"
"qhelp.dtd">
<qhelp>
<overview>
<p>
This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file.
</p>
<p>
A file that contains many lines that are duplicated within the code base is problematic
for a number of reasons.
</p>
</overview>
<include src="DuplicationProblems.qhelp" />
<recommendation>
<p>
Refactor files with lots of duplicated code to extract the common code into
a shared library or module.
</p>
</recommendation>
<references>
<li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Duplicate_code">Duplicate code</a>.</li>
<li>M. Fowler, <em>Refactoring</em>. Addison-Wesley, 1999.</li>
</references>
</qhelp>