Python Block Comments

You may have read on Stack Overflow (such as a comment on the approved answer) or other sites that you could use triple quotes as block comments in Python… in fact the author of Python (Guido van Rossum) mentioned in a tweet a few years back and that quote seems to be the source of much of this philosophy:

Even today, this Twitter post is being cited on Stack Overflow and other sites as a reasonable solution to block comments.  Look in Python code in Github and a plethora of triple quote comments are used.

New to Python, I thought that the triple quote comments were the equivalent of /* */ in Groovy/Java.    However, triple quotes are special.

Triple quotes are either:

  • Docstrings
  • Multi-Line Strings

Docstrings

If a triple quote is placed just after a class or function definition – they are treated as a docstring. Which is a string used for things like help/info that the user can access while the application is running. Consider this quote about docstrings from Wikipedia:

Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, docstrings are not stripped from the source tree when it is parsed, but are retained throughout the runtime of the program. This allows the programmer to inspect these comments at run time, for instance as an interactive help system, or as metadata.

Considering the above quote, it seems to me that docstrings as block comments wouldn’t be a good idea.  It’s carrying the comment into the runtime environment.  It’s not needed in runtime, it’s a source code comment.  Nor should it be checked for syntax, or other programatic problems.

Multi-Line Strings

As for triple quotes that are multi-line strings… well those multi-line strings are equally bad of choice for comments, as mentioned here.   When the multi-line string is present it isn’t ignored the same way the # (single line comments) are.

Further, in Python 3, the multi-line strings can generate syntax errors as seem below.

Syntax Checking

In trying to integrate a Python 2 library into my Python 3 code, I hit this error:

SyntaxError: (unicode error) ‘unicodeescape’ codec can’t decode bytes in position 14-15: malformed \N character.

I was confused because the \N was part of what I thought was a block comment (that triple quote.)  Inside the triple quote block was a like that made mention of a file path:

(i.e. \Device\NPF_..)

While Python 2 seems ok with the escaped sequence within a docstring or triple quote.

However in Python 3, it throws the above Syntax error.  To test it out, just run this code in Python 3:

"""
\N
"""

You can try single quotes as well.  What is occurring is that the triple quotes are being checked for syntax.  It shouldn’t be.  But it is, at least in Python 3.

Even if no error is being generated, the Python interpreter is checking each line of the docstring for syntax.

The author of the library (the one I was trying to import), choose a solution of escaping the backslashes (\\Device\\NPF), this removed the error, but it still has a persistent problem – the comment is being checked for valid syntax when it shouldn’t be.

Maybe the performance impact is minimal, but why use it if it makes performance worse to any degree.

Docstrings When Needed

If you need a docstring, use it of course.  Some examples of useful docstrings are over at this link.

However if you need a comment, why use it as a docstring or multi-line string?  It’s adding on syntax checking that isn’t needed and pushes the source code comment into the runtime environment (again where it isn’t needed.)  It also can throw odd errors on syntax, when you are simply putting in characters like \N.

Comments as Single Line Comments

However, if you use the simple # to comment that line, no error results as it isn’t being interpreted.

If you really want to comment out a block in Python, use # on each line.  In most IDE’s you can just CMD+/  (or CNTRL+/ on a PC) on highlighted rows to comment them out.

While Python 2 didn’t error on this, I wonder if it still is interpreting those triple quotes.  If it is, then a performance hit is being taken.   I really don’t want to make my code run slower.  Regardless if you write your triple comment to be interpreted without error – they are still being interpreted.

It would be best if they were complete ignored… so no time is taken to see if there is any syntax error in the comment.  That’s why I use single line comments in Python.

Python Block Comments
User Rating: 0 (0 votes)