mirror of
https://github.com/github/codeql.git
synced 2026-04-14 03:24:06 +02:00
34 lines
1.3 KiB
XML
34 lines
1.3 KiB
XML
<!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 expectations 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>
|