mirror of
https://github.com/github/codeql.git
synced 2025-12-25 21:26:37 +01:00
35 lines
1.5 KiB
XML
35 lines
1.5 KiB
XML
<!DOCTYPE qhelp PUBLIC
|
|
"-//Semmle//qhelp//EN"
|
|
"qhelp.dtd">
|
|
<qhelp>
|
|
<overview>
|
|
<p>This metric measures the percentage of lines in a file that contain a comment or are part of a
|
|
multi-line comment. Note that this metric ignores docstrings.</p>
|
|
|
|
<p>The percentage of comment lines should always be considered with the value for the related metric
|
|
"Percentage of docstrings". For public modules, functions, classes and methods docstrings are the
|
|
preferred method of documentation because the information can be inspected by the program at runtime,
|
|
for example, as an interactive help system or as metadata for a function.</p>
|
|
|
|
<p>Having a low percentage of comments and docstrings is an indication that a file does not have
|
|
sufficient documentation. Undocumented code is difficult to understand, modify, and reuse.</p>
|
|
|
|
</overview>
|
|
<recommendation>
|
|
<p>Add documentation to files with a low comment and docstring ratio. Use docstrings to document
|
|
public modules, functions, classes and methods.</p>
|
|
|
|
</recommendation>
|
|
<references>
|
|
|
|
<li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Need_for_comments">
|
|
Need for comments</a>.</li>
|
|
<li>Python PEP 8: <a href="http://www.python.org/dev/peps/pep-0008/#comments">Comments</a>.</li>
|
|
<li>Python for Beginners: <a href="http://www.pythonforbeginners.com/basics/python-docstrings/">
|
|
Python Docstrings</a>.</li>
|
|
<li>Python PEP 257: <a href="http://www.python.org/dev/peps/pep-0257/">Docstring Conventions</a>.</li>
|
|
|
|
|
|
</references>
|
|
</qhelp>
|