mirror of
https://github.com/github/codeql.git
synced 2025-12-25 13:16:33 +01:00
40 lines
1.2 KiB
XML
40 lines
1.2 KiB
XML
<!DOCTYPE qhelp PUBLIC
|
|
"-//Semmle//qhelp//EN"
|
|
"qhelp.dtd">
|
|
<qhelp>
|
|
|
|
|
|
<overview>
|
|
<p>PEP8 mandates that all public modules, classes, functions and methods should have a documentation
|
|
string. Ensuring that every public module, class, function and method is documented makes it easier
|
|
for other developers to maintain the code.
|
|
</p>
|
|
|
|
</overview>
|
|
<recommendation>
|
|
|
|
<p>If a module, class, function or method needs to be public then add a documentation string that
|
|
describes the
|
|
purpose or use of the object (see PEP 257 for guidelines). If the object does not need to be public
|
|
then make it "private" by changing its name from <code>xxx</code> to <code>_xxx</code>.</p>
|
|
|
|
</recommendation>
|
|
<example>
|
|
<p>The following simple, public function should be updated to include a documentation string
|
|
immediately after the <code>def</code> line.</p>
|
|
<sample src="DocStrings.py" />
|
|
|
|
<p>You might insert the documentation string: <code>"""Return the sum of x and y."""</code> on line 2.
|
|
|
|
</p></example>
|
|
<references>
|
|
|
|
<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">Documentation string conventions
|
|
</a>.</li>
|
|
|
|
|
|
|
|
</references>
|
|
</qhelp>
|