<!DOCTYPE qhelp PUBLIC

"-//Semmle//qhelp//EN"

"qhelp.dtd">

<qhelp>

<overview>

<p>

This metric measures the number of comment lines for each type.

</p>

<p>

Whilst the absolute number of comment lines in a type may not provide much

useful information out of context, a very small number of comments in a type

may indicate either a potentially worrying lack of documentation or that the

type 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 type 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 types 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 types 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 types 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>