<!DOCTYPE qhelp PUBLIC
  "-//Semmle//qhelp//EN"
  "qhelp.dtd">
<qhelp>


<overview>
<p>
Functions that are called from lots of different places are usually important, and justify having documentation written for them.
In particular, if a function is defined in a file, and is called from at least two other files, then the function should probably be documented.
</p>
<p>
As an exception, because their purpose is usually obvious, it is not necessary to document constructors, destructors, implementations of <code>operator=</code>, or functions with fewer than five lines of code.
</p>
</overview>
<recommendation>
<p>
Add comments to document the purpose of the function. In particular, ensure that the public API of the function is carefully documented. This reduces the chance that a future change to the function will introduce a defect by changing the API and breaking the expections of the calling functions.
</p>

</recommendation>
<references>

<li>
  C++ Programming Wikibook: <a href="http://en.wikibooks.org/wiki/C%2B%2B_Programming/Programming_Languages/C%2B%2B/Code/Style_Conventions#Comments">Comments</a>
</li>
<li>
  Wikipedia: <a href="http://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Need_for_comments">Need for comments</a>
</li>


</references>
</qhelp>
