Python comments: # vs strings

Question

I have a question regarding the "standard" way to put comments inside Python source code:

def func():
    "Func doc"
    ... <code>
    'TODO: fix this'
    #badFunc()
    ... <more code>

def func():
    "Func doc"
    ... <code>
    #TODO: fix this
    #badFunc()
    ... <more code>

I prefer to write general comments as strings instead of prefixing #'s. The official python style guide doesn't mention using strings as comments (If I didn't miss it while reading it)

I like it that way mainly because I think the # character looks ugly with comment blocks. As far as I know these strings don't do anything.

The question is: Are there disadvantages in doing this?

Answer 1

I think that only the first string literal in a definition (or class) is "special", i.e. gets stored by the interpreter into the defined object's (or class') docstring.

Any other string literals you place in the code will, at the worst, mean the interpreter will build the string value at run-time, and then just throw it away. This means that doing "comments" by littering the code with string constants might cost, performance-wise.

Of course, I have not benchmarked this, and also don't know the Python interpreter well enough to say for sure.

Answer 2

The disadvantage, of course, is that someone else reading it will find that the code strings and comment strings are interleaved, which could be confusing.

Answer 3

Don't misuse strings (no-op statements) as comments. Docstrings, e.g. the first string in a module, class or function, are special and definitely recommended.

Note that docstrings are documentation, and documentation and comments are two different things!

• Documentation is important to understand what the code does.
• Comments explain how the code does it.

Documentation is read by people who use your code, comments by people who want to understand your code, e.g. in order to maintain it.

Using strings for commentation has the following (potential) disadvantages:

• It confuses people who don't know that the string does nothing.
• Comments and string literals are highlighted differently in code editors, so your style may make your code harder to read.
• It might effect performance and/or memory usage (if the strings are not removed during bytecode compilation, removing comments is done on the scanner level so its definitively cheaper)

Most important for Python programmers: It is not pythonic:

There should be one-- and preferably only one --obvious way to do it.

Stick to the standards, use comments.