mirror of
https://github.com/github/codeql.git
synced 2026-01-02 17:26:44 +01:00
56 lines
1.5 KiB
XML
56 lines
1.5 KiB
XML
<!DOCTYPE qhelp PUBLIC
|
|
"-//Semmle//qhelp//EN"
|
|
"qhelp.dtd">
|
|
<qhelp>
|
|
<overview>
|
|
<p>
|
|
This metric measures the number of comment lines for each file.
|
|
</p>
|
|
|
|
<p>
|
|
Whilst the absolute number of comment lines in a file may not provide much
|
|
useful information out of context, a very small number 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>
|
|
If the file is not an auto-generated one, it should be documented at the first
|
|
convenient opportunity (i.e. now). We note in passing that:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
From a pragmatic standpoint, it is clear that not all files are equally
|
|
important to document, so some common sense needs to be applied when deciding
|
|
which code should be documented first.
|
|
</li>
|
|
|
|
<li>
|
|
Documenting entire files after the fact is not only onerous, but also often
|
|
yields lower-quality documentation than would have been written by the
|
|
original author at the time of writing the code (because other developers
|
|
may not understand the context as well as the person who wrote the code).
|
|
For this reason, finding completely undocumented files should be treated as
|
|
a sign that your documentation practices in general need to improve.
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
</recommendation>
|
|
<references>
|
|
|
|
|
|
<li>
|
|
S. McConnell. <em>Code Complete</em>, 2nd Edition. Microsoft Press, 2004.
|
|
</li>
|
|
|
|
|
|
</references>
|
|
</qhelp>
|