and are indented to the same level as that code. Each line of a block
comment starts with a # and a single space (unless it is indented text
inside the comment).
Paragraphs inside a block comment are separated by a line containing a
single #.
Inline Comments
Use inline comments sparingly.
An inline comment is a comment on the same line as a statement. Inline
comments should be separated by at least two spaces from the statement.
They should start with a # and a single space.
Inline comments are unnecessary and in fact distracting if they state
the obvious. Don't do this:
x = x + 1 # Increment x
But sometimes, this is useful:
x = x + 1 # Compensate for border
Documentation Strings
Conventions for writing good documentation strings (a.k.a. "docstrings")
are immortalized in PEP 257 [3].
- Write docstrings for all public modules, functions, classes, and
methods. Docstrings are not necessary for non-public methods, but you
should have a comment that describes what the method does. This comment
should appear after the "def" line.
- PEP 257 describes good docstring conventions. Note that most
importantly, the """ that ends a multiline docstring should be on a line
by itself, and preferably preceded by a blank line, e.g.:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
- For one liner docstrings, it's okay to keep the closing """ on the same
line.
Version Bookkeeping
If you have to have Subversion, CVS, or RCS crud in your source file, do
it as follows.
__version__ = "$Revision: 00f8e3bb1197 $"
# $Source$
These lines should be included after the module's docstring, before any
other code, separated by a blank line above and below.
Naming Conventions
The naming conventions of Python's library are a bit of a mess, so we'll
never get this completely consistent -- nevertheless, here are the
currently recommended naming standards. New modules and packages
(including third party frameworks) should be written to these standards,
but where an existing library has a different style, internal consistency
Style Guide For Python Code
Start from the beginning
