Multiline comments in Python

How can you comment out a block of code in Python?

Does Python have multi-line comments?

Single-line comments in Python uses the octothorpe character (#), also known as pound, number sign, crunch, and of course, the hashtag character:

# This is a comment

this = "is not a comment"

But what if you want to comment out a whole block of code?

Unlike some programming languages, Python does not have multi-line comments.

What about triple quotes?

You might be thinking, wait, I've seen code that seems like a multi-line comment before, haven't I? Aren't triple quotes used for multi-line comments?

This code has two versions of the same is_prime function:

from math import sqrt


def is_prime(candidate):
    if candidate < 2:
        return False
    for n in range(2, candidate):
        if candidate % n == 0:
            return False
    return True


def is_prime(candidate):
    if candidate < 2:
        return False
    for n in range(2, sqrt(candidate)):
        if candidate % n == 0:
            return False
    return True

The second version doesn't quite work, so it will raise an exception.

Let's wrap this second version of this function in triple quotes:

from math import sqrt


def is_prime(candidate):
    if candidate < 2:
        return False
    for n in range(2, candidate):
        if candidate % n == 0:
            return False
    return True


"""
def is_prime(candidate):
    if candidate < 2:
        return False
    for n in range(2, sqrt(candidate)):
        if candidate % n == 0:
            return False
    return True
"""

Is this a multi-line comment?

Yes... but actually no.

The Python interpreter is smart enough to skip over this multi-line string, because it knows that it doesn't do anything. But that's not actually a documented Python feature.

So while you can use triple quotes to make something that acts like a multi-line comment, you probably shouldn't.

Docstrings versus comments

What about multi-line strings like this?

from math import isqrt


def is_prime(candidate):
    """
    Return True if candidate number is prime.

    Returns True if the number has a factor besides 1 and itself.
    Returns False for numbers below 2.
    """
    if candidate < 2:
        return False
    # Note that we're using isqrt because range only accepts integers
    for n in range(2, isqrt(candidate)+1):
        if candidate % n == 0:
            return False
    return True

Isn't that multi-line string actually a multi-line comment?

While this does act as documentation, it's not a comment. Comments are completely skipped over by Python. But Python actually reads that string! That string is a docstring.

When the first line in a function is a string all on its own, Python reads that string as documentation, and it stores that docstring on the function, so that tools like help can find it.

Usually, when I find myself wanting to add a multi-line comment to code, I realize that I could use a docstring instead.

Comments are for adding context to your code. But if you want to add context to an entire function, class, or module, a docstring is a great way to do it! They can be single line or multi-line.

What if I want to comment-out a whole block of code?

What if you have a whole block of code that you'd like to comment out?

Well, if you're trying to delete a block of code but you don't want to lose it, and you're using Git (or a similar version control system) I would commit that code to Git and then delete it. You can always go find the Git commit that included that code later.

But what if you just need to quickly comment out a block of code, do some work for a few minutes, and then uncomment that code? Well, triple quotes are pretty great for that. Although, depending on your text editor, there's probably an even easier way to quickly comment and uncomment some code.

How to comment multiple lines

Most code editors have a way to highlight multiple lines of code and comment out all the selected lines at once:

from math import sqrt


def is_prime(candidate):
    if candidate < 2:
        return False
    for n in range(2, candidate):
        if candidate % n == 0:
            return False
    return True


# def is_prime(candidate):
#     if candidate < 2:
#         return False
#     for n in range(2, sqrt(candidate)):
#         if candidate % n == 0:
#             return False
#     return True

In many text editors, it's Ctrl + / (or ⌘ + / on Mac) and you can usually use the same shortcut to uncomment the same code.

Many text editors will also continue a comment onto the next line, if you're writing a comment and you hit Enter to go to the next line.

So when you need to write a comment that spans over multiple lines, I prefer to use a # character before each line, instead of using a multi-line string.

Use docstrings, your code editor, or version control

The next time you find yourself wanting a multi-line comment in Python, ask yourself, what do I need this for?

If you need to temporarily comment out a block of code, you can probably use a keyboard shortcut in your text editor.

If you're trying to write documentation, you probably want a docstring instead of a comment. But if you really do want a comment and not for documentation, I would put a hash character before each line instead of using a multi-line string. That convention is more widely used, and probably easier to understand for most people reading your code.