Home/

...

/

Comments

Comments

This lesson is about commenting techniques in Python.

A Few Points to Ponder

  1. Comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes!

  2. Comments should be complete sentences. The first word should be capitalized unless it is an identifier that begins with a lower case letter (never alter the case of identifiers!).

  3. Block comments generally consist of one or more paragraphs built out of complete sentences, with each sentence ending in a period.

  4. You should use two spaces after a sentence-ending period in multi-sentence comments, except after the final sentence.

  5. When writing English, follow Strunk and White.

  6. Python coders from non-English speaking countries: please write your comments in English, unless you are 120% sure that the code will never be read by people who don’t speak your language.

Block Comments

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 #.

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:

Press + to interact
x = x + 1  # Increment x

But sometimes, this is useful:

Press + to interact
x = x + 1  # Compensate for border

Documentation Strings

Conventions for writing good documentation strings (a.k.a. “docstrings”) are immortalized.

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.

Note that most importantly, the “”" that ends a multiline docstring should be on a line by itself:

Press + to interact
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""

For one liner docstrings, please keep the closing “”" on the same line.