mirror of
https://github.com/github/codeql.git
synced 2025-12-25 13:16:33 +01:00
54 lines
1.6 KiB
XML
54 lines
1.6 KiB
XML
<!DOCTYPE qhelp PUBLIC
|
|
"-//Semmle//qhelp//EN"
|
|
"qhelp.dtd">
|
|
<qhelp>
|
|
|
|
<overview>
|
|
<p>A comment that includes the word <code>TODO</code> often marks a part of
|
|
the code that is incomplete or broken, or highlights ambiguities in the
|
|
software's specification.</p>
|
|
|
|
<p>For example, this list of comments is typical of those found in real
|
|
programs:</p>
|
|
|
|
<ul>
|
|
<li><code>TODO: move this code somewhere else</code></li>
|
|
<li><code>TODO: find a better solution to this workaround</code></li>
|
|
<li><code>TODO: test this</code></li>
|
|
</ul>
|
|
|
|
</overview>
|
|
<recommendation>
|
|
|
|
<p>It is very important that <code>TODO</code> comments are
|
|
not just removed from the code. Each of them must be addressed in some way.</p>
|
|
|
|
<p>Simpler comments can usually be immediately addressed by fixing the code,
|
|
adding a test, doing some refactoring, or clarifying the intended behavior of
|
|
a feature.</p>
|
|
|
|
<p>In contrast, larger issues may require discussion, and a significant amount
|
|
of work to address. In these cases it is a good idea to move the comment to an
|
|
issue-tracking system, so that the issue can be tracked
|
|
and prioritized relative to other defects and feature requests.</p>
|
|
|
|
</recommendation>
|
|
<example>
|
|
<p>The following example shows a function where a TODO comment indicates a known limitation in the
|
|
existing implementation. The function should be reviewed, the limitation addressed and then the
|
|
comment deleted.</p>
|
|
|
|
<sample src="ToDoComment.py" />
|
|
|
|
</example>
|
|
<references>
|
|
|
|
<li>
|
|
Wikipedia: <a href="http://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Tags">
|
|
Comment tags</a>.
|
|
</li>
|
|
|
|
|
|
</references>
|
|
</qhelp>
|