-The following guidelines seem to be most commonly agreed upon:
-
-**Wrong or outdated comments are worse than no comments at all.** Following the
-saying that it is better, on a boat, to know that we do not know were we are
-than to wrongly believe we know where we are, wrong or outdated comments can be
-misleading for the maintainers, slow down considerably bug hunting or
-refactoring, and then, when discovered wrong, they will throw suspicion on all
-other comments in the code, regardless of their individual correctness.
-
-**There's no need to comment perfect code...** An hypothetical perfectly readable
-code, with a crystal clear logic stream, expressive variable and function
-names, orthogonal segmentation passing exactly between the flesh and the bones,
-and no implicit assumptions of any kind, would not require any comment at all.
-When striving for coding excellence, it is useful to see any existing comment,
-or any feeling of a need for a comment, as the sign that the code do not
-express clearly enough its intent and can be improved.
-
-**.. but no code is perfect.** Perfect code is a chimera, it exists only in
-our dreams. In real life, a code base is full of trade offs, and comments are
-often needed in the most difficult parts. Moreover, any special case, any
-obscure hack, any monkey patch and any ugly workaround MUST be signaled and
-explained by a proper comment. This should be enforced by the law!
-
-**TODOs** are special comments that a developer write as a reminder for later
-use. It is said that its original intent was that someone might, one day,
-search for the string "TODO" in the code base and actually roll their sleeves
-and start *to do the TODOs*. There is no available record that it ever
-happened. However, TODOs comment are still very useful, because they mark the
-current limits of the code, and it is not unlikely that, when required to add a
-new behavior to the actual code, looking at the TODOs will show where to start.
-
-**Do not use triple-quote strings to comment code.** A common operation when
-modifying code is to comment out some lines or even a full function or class
-definition. This can be done by adding triple-quotes around the code block to
-be skipped, but this is not a good practice, because line-oriented command-line
-tools such as ``grep`` will not be aware that the commented code is inactive.
-It is better to add hashes at the proper indentation level for every commented
-line. Good editors allow to do this with few keystrokes (ctrl-v on Vim).
-
-**Bad**
-
-.. code-block:: python
-
- def tricky_function():
- '''
- Commented out because its breaks something.
- if foo:
- do_bar()
- '''
- return baz
-
- def tricky_function():
- # Commented out because its breaks something.
- #if foo:
- #do_bar()
- return baz
-
-
- def tricky_function():
- # Commented out because its breaks something.
- # if foo:
- # do_bar()
- return baz
-
-**Good**
-
-.. code-block:: python
-
- def tricky_function():
- # Commented out because its breaks something.
- #if foo:
- # do_bar()
- return baz
-
-Note that comment text is properly written and separated from the hash by a
-space. Commented code is not separated from the hash by an additional space;
-this helps when uncommented the code.
-
-The Basics
-::::::::::
-
-
-Code Comments
--------------
-
-Information regarding code comments is taken from PEP 008 (http://www.python.org/dev/peps/pep-0008/).
-Block comment styling should be used when commenting out multiple lines of code.: ::
-
- 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 #.
-
-In-line 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
- 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
-
-Docstrings
------------