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

Add missing QHelp files

Browse Source
This commit is contained in:
Arthur Baars
2020-09-01 12:18:38 +02:00
parent f4060723bb
commit aedfa47cb4
50 changed files with 754 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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>