mirror of
https://github.com/github/codeql.git
synced 2026-06-22 13:21:10 +02:00
72 lines
2.1 KiB
XML
72 lines
2.1 KiB
XML
<!DOCTYPE qhelp PUBLIC
|
|
"-//Semmle//qhelp//EN"
|
|
"qhelp.dtd">
|
|
<qhelp>
|
|
<overview>
|
|
<p>
|
|
This metric measures the (absolute) number of comment lines for each method.
|
|
</p>
|
|
|
|
<p>
|
|
Whilst the absolute number of comment lines a method has is not always
|
|
especially meaningful when taken out of context, methods with very few
|
|
comment lines are almost undocumented and may be hard to understand.
|
|
</p>
|
|
|
|
</overview>
|
|
<recommendation>
|
|
|
|
<p>
|
|
Methods containing very few comments should be examined to see whether or not
|
|
they need more documentation. At a minimum, most methods (aside from getters,
|
|
setters and other trivial methods) usually benefit from at least a brief
|
|
comment as to their purpose. Less trivial methods can often be improved by
|
|
adding appropriate comments to communicate the programmer's intent, or to
|
|
summarize what a bit of code does. (See [McConnell] for more on writing good
|
|
comments.)
|
|
</p>
|
|
|
|
<p>
|
|
There are some cases, however, where adding more comments should not be the
|
|
main focus of refactoring:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
If your method is very long, the priority is to break it up into smaller
|
|
methods with sensible names that communicate intent. These new methods
|
|
should then be commented appropriately.
|
|
</li>
|
|
|
|
<li>
|
|
If your method is very hard to understand, you should redesign the way
|
|
it works to make things simpler. Tricky code is bad code - you shouldn't
|
|
document it, you should rewrite it (and then document it).
|
|
</li>
|
|
|
|
<li>
|
|
If your method is already absolutely clear and you don't have anything useful
|
|
to say, don't add meaningless comments. Comments are there to communicate
|
|
information that is not obvious from the code, not to repeat what's already
|
|
there. If you can't say something that couldn't be generated by an automatic
|
|
documentation generator (see [Atwood]), don't say anything.
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
</recommendation>
|
|
<references>
|
|
|
|
|
|
<li>
|
|
J. Atwood. <a href="http://www.codinghorror.com/blog/2005/11/avoiding-undocumentation.html">Avoiding Undocumentation</a>. Published online, 2005.
|
|
</li>
|
|
<li>
|
|
S. McConnell. <em>Code Complete</em>, 2nd Edition. Microsoft Press, 2004.
|
|
</li>
|
|
|
|
|
|
</references>
|
|
</qhelp>
|