How to Add Multiline Comments in Python

Adding comments to our Python code is an important task that many programmers are familiar with. More often than not, we find that we need to add multiline comments to our code in Python.

Surprisingly, there is actually no out of the box solution to adding multiline comments in Python. The two workarounds that we can use to add multiline comments is to add a # for each line of comment or to use triple-quoted strings.

In this post and video that follows, we’ll discuss the two workarounds and explain why a triple-quoted string is actually not a comment (and how we can prevent it from being interpreted as a non-comment by the interpreter). We’ll also discuss how we can use a keyboard shortcut to comment out multiple lines of code in Python.

Adding a # For Each Line Of Comment

The first method to add multiple lines of comment in our Python code is to add a # for each line. For instance, if we want the following block of text to be a comment:

This is a long comment
that spans more
than one line

We do it as follows:

# This is a long comment
# that spans more
# than one line

When we add a # in front of each line of text, we turn that line into a comment. Hence, the block of text above effectively changes into three lines of comment.

Keyboard Shortcuts to Add Multiline Comments

In most cases, the text editor or IDE that you use is able to convert blocks of text into comments. For instance, if you use IDLE, you can select the text that you want to convert to comments and press Alt-3 on your keyboard (option-3 for Mac OS).

IDLE will then add two # to each line of the selected text to convert them to comments (one # is enough, but IDLE adds two, which is fine too).

Alternatively, you can select the text and click on Format > Comment Out Region in the menu bar.

After converting the text to comments, if you want to convert the comments back to text, you can select the comments and press Alt-4 or option-4. Alternatively, you can click on Format > Uncomment Region in the menu bar.

Using Triple-Quoted Strings

Another method to add multiline comments to your Python code is to use triple-quoted strings. For instance, to convert the following block of text to a comment,

You can convert a block
of text to a comment by
using triple quotes.

We can enclose the block with three single quotes (''') or double quotes ("""), as shown in the examples below:

'''
You can convert a block
of text to a comment by
using triple quotes.
'''

""" 
You can convert a block 
of text to a comment by 
using triple quotes. 
"""

Triple-Quoted Strings Are Technically Not Comments

However, when we use tripled-quoted strings, technically speaking, they are not comments. Depending on where they appear in your code, they may be treated as docstrings and are not ignored by the interpreter.

A docstring is a documentation string that can be added to our Python modules, functions, classes, and methods to explain what the code does (not how it does it). These strings are not ignored by the interpreter and can be accessed using the __doc__ attribute of an object or using the built-in help() function.

Any triple-quoted string that appears occurs as the first statement of a module, function, class or method is treated as a docstring.

For instance, if we have the following function:

def docStringDemo():

    '''This function simply
prints the word Hello'''

    print('Hello')

Lines 3 and 4 is a docstring.

Displaying Docstrings

To display the docstring, we can use a special attribute called __doc__:

print(docStringDemo.__doc__)

This gives us the following output:

This function simply
prints the word Hello

Alternatively, we can use the built-in help() function:

help(dosStringDemo)

This gives us the following output:

Help on function docStringDemo in module __main__:

docStringDemo()
    This function simply
    prints the word Hello

Using Triple-Quoted Strings as Comments

Any triple-quoted string that appears as the first statement in a function is treated as a docstring. In contrast, if we move the string down, it is no longer a docstring and is ignored by the interpreter. For instance, if we have the following function

def justACommentDemo():

    print('Hello')

    '''This function simply
prints the word Hello'''

The triple-quoted string on lines 5 and 6 is NOT a docstring as they occur after the first statement.

This string is ignored by the interpreter and works as a comment. If we try to display the __doc__ attribute

print(justACommentDemo.__doc__)

we’ll get

None

as the output.

Indentation Matters

When using triple-quoted strings as comments, the leading triple quote must be indented appropriately to avoid an IndentationError.

For instance,

def docStringError():

'''
This leads to an error
'''

    print('Hello')

gives us an error while

def docStringError():

    '''
This leads to an error
'''

    print('Hello')

is fine (as the first triple-quote is indented).