2011年8月23日 星期二

PEP 8 -- Style Guide for Python Code (3)

Comments
1. Block comments
  a. Block comments generally apply to some (or all) code that follows them, 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 #.
2. Inline comments
  a. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

Documentation Strings
1. 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.
2. 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.

"""

3. For one liner docstrings, it's okay to keep the closing """ on the same line.

沒有留言:

張貼留言