hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-04-27 17:55:19 +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>