kennethreitz/python-guide
1
0
Fork 0
mirror of https://github.com/kennethreitz/python-guide.git synced 2026-06-05 23:00:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Attempting to fix markup...

Browse Source
This commit is contained in:
Aaron
2011-04-26 07:58:07 -07:00
parent d84ef20f67
commit 5eeea52215
1 changed files with 4 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/writing/documentation.rst
+4 -3
View File
@@ -22,20 +22,21 @@ Block comment styling should be used when commenting out multiple lines of code.
single #. single #.
Inline comments are used for individual lines and should be used sparingly.: :: Inline comments are used for individual lines and should be used sparingly.: ::
An inline comment is a comment on the same line as a statement. Inline 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. comments should be separated by at least two spaces from the statement.
They should start with a # and a single space. They should start with a # and a single space.
Inline comments are unnecessary and in fact distracting if they state Inline comments are unnecessary and in fact distracting if they state
the obvious. Don't do this: the obvious. Don't do this:
x = x + 1 # Increment x x = x + 1 # Increment x
But sometimes, this is useful: But sometimes, this is useful: ::
x = x + 1 # Compensate for border x = x + 1 # Compensate for border
Doc Strings Doc Strings
----------- -----------
PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/) PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/)
There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory. |There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory.
One-line docstrings: :: |One-line docstrings: ::
def kos_root(): def kos_root():
"""Return the pathname of the KOS root directory.""" """Return the pathname of the KOS root directory."""