CLinesOfComment.qhelp

<!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>