How to Make Multiline Comments in Python

In this tutorial, we explain the two methods used to make multiline comments in Python, with examples. There are some drawbacks to one of the methods, so pay attention.

Code without comments is like a story written in a language you only half understand. You might be able to figure out the main points, but you’ll miss some nuances and it would be way easier with a translation alongside it. Most coders hate code with no comments or limited comments, so finding ways to clearly explain what a function or block of code does is an essential part of working with a team.

Python does not make it that easy. In a lot of programming languages, you can spread comments over multiple lines, making them easier to follow and better laid-out on your screen. Strictly speaking, Python can’t do that. Fortunately, there are two different workarounds that can help make your Python code more readable and make your team appreciate you that little bit more.

Option 1: Multiple Single Line Comments

By far the simplest workaround is just to comment out multiple individual lines of code. For example:

# This is a single line Python comment
# I can make many comments
# over multiple lines
# which works as a multiline comment

This is the most common approach because of how easy it is. It’s also the approach Python’s own style guide prefers, so it’s what other programmers will be expecting. Obviously, sticking to conventions and best practices like this makes everyone’s life easier on a shared project, so this should be your go-to approach most of the time.

Keyboard Shortcut

Commenting out multiple lines of code takes a few extra keystrokes. It’s repetitive and laborious, and it can really interrupt your train of thought. Since commenting should be the easiest part of coding, this is not ideal. You can get around the issue in most of the Python-friendly text editors.

For example, if you are using the Sublime Text Editor on Mac, select the block of lines you want to turn into comments, then press cmd + /. This adds the hashtag and turns the whole block into comments that the parser ignores. You can undo this action in exactly the same way: select a block of comments, press cmd + /, and they revert to normal lines of code.
There are similar features in other text editors, such as VS Code and Atom.

Option 2: Using Multi-line Strings

This one’s a little bit different. Rather than create comment blocks line by line, you can create multi-line string variables instead. The syntax to create a string is simply “””, so a block comment using this syntax looks like:

"""
This comment
spans multiple lines
and sits within the 2 syntaxes.
"""

Pros of using multi-line strings

The best part of this approach is that you can easily insert the string into the middle of a function to explain exactly what a complex piece of code does. For example:

def sum_abc(a, b, c):
result = a + b + c
"""
Sum the three variables a, b and c
Then return the resulting calculation
"""
return result

That’s really the main benefit of handling multi-line comments this way.

Cons of using multi-line strings

The biggest drawback to this approach is that it doesn’t create an actual comment. It creates a string constant that the code then doesn’t use for anything. This orphaned constant doesn’t show up in the CPython bytecode disassembly, but if you place the “comment” in certain places, it can have unexpected consequences.

If you put a multi-line string at the start of a module, after a function signature, or after a class definition, Python reads it as a docstring (documentation string). For example:

def sum_abc(a, b, c):
"""
Sum the three variables a, b and c
Then return the resulting calculation
"""
result = a + b + c
return result

These statements are processed as code, which is messy and slows down your code, albeit by an infinitesimal amount.

In addition, if you don’t indent the string just right in your block of code, you’ll generate a Syntax Error, so this technique requires more finesse and attention to detail than just writing multiple single-line comments.

So, there you have it. Two ways to get around Python’s lack of simple multi-line comments. Creating multiple single-line comments is standard, simple, and predictable, so it’s probably best to stick to this method in most cases, but it’s always great to have options.