mirror of
https://github.com/github/codeql.git
synced 2025-12-23 04:06:37 +01:00
36 lines
1.4 KiB
XML
36 lines
1.4 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 docstring. Note that this
|
|
metric ignores comments.
|
|
|
|
</p><p>Docstrings are a good way to associate documentation with a specific object in Python. 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 docstrings is often an indication that a file has insufficient
|
|
documentation. However, the value for the related metric "Percentage of comments" should also be
|
|
considered because packages and non-public methods may be documented using comments. Undocumented
|
|
code is difficult to understand, modify, and reuse.</p>
|
|
|
|
</overview>
|
|
<recommendation>
|
|
<p>Add documentation to files with a low docstring ratio. It is most useful to start documenting
|
|
the public functions first.</p>
|
|
|
|
</recommendation>
|
|
<references>
|
|
|
|
<li>Python for Beginners: <a href="http://www.pythonforbeginners.com/basics/python-docstrings/">
|
|
Python Docstrings</a>.</li>
|
|
<li>Python PEP 8: <a href="http://www.python.org/dev/peps/pep-0008/#documentation-strings">Documentation
|
|
Strings</a>.</li>
|
|
<li>Python PEP 257: <a href="http://www.python.org/dev/peps/pep-0257/">Docstring Conventions</a>.</li>
|
|
|
|
|
|
</references>
|
|
</qhelp>
|