How to Comment Code in Python: Inline, Multiline, and Docstring

Jeremy GrifskiJanuary 21st, 2020Last Updated: June 23rd, 2020

0 61 5 minutes read

As we kick off 2020, I wanted to start getting back to some of my favorite content: Python “how to” content. Today, we’ll be looking at how to comment code in Python—a skill we should all have.

To summarize, there are three main ways to make comments in Python. To make inline comments, use the hash mark, #. To make multiline comments, use a hash mark on every line. Alternatively, use triple quotes, """. These kick off a multiline string which can be used to simulate comments. For more details, check out the options below.

Problem Description

One thing I’ve done throughout this series is create content that targets a specific issue and address it with a few solutions. Of course, many of those solutions require some fundamental understanding of how Python works. In other words, at no point have I actually written any of those fundamental articles. Well, I suppose it’s better late than never.

Today, I want to look at a few ways of commenting code in Python. For those that don’t know, comments are ways of documenting code directly. Specifically, a comment is text that has no semantic affect on your programs. In other words, comments don’t do anything but provide context for the reader.

As an example, we might want to write some mathematical expression like the Pythagorean Theorem:

a_squared = 3**2
b_squared = 4**2
c_squared = a_squared + b_squared

Clearly, this expression resembles the Pythagorean Theorem based on variable name choices alone. However, not everyone will be able to tell at first glance. In other words, we might want to add a comment that tells the reader what the purpose of this expression is. For example, we might say “uses the Pythagorean Theorem to compute c^2.” How do we go about doing that? Luckily, this article will give us a few options.

Solutions

In this portion of the article, we’ll take a look at a few different ways to write comments in Python. Keep in mind that this isn’t really an article on commenting styles or even a commentary on how to write comments. Instead, we’ll just be sharing the syntax. It’s up to you to figure out how you want to use the tools provided.

Inline Comments

In Python, you can create a comment using the hash mark, #. As soon as this mark appears, everything following it until the end of the line is considered a comment:

# Uses the Pythagorean Theorem to compute c^2
a_squared = 3**2
b_squared = 4**2
c_squared = a_squared + b_squared

Since comments don’t start until the hash mark appears, we can comment the ends of lines as well:

# Uses the Pythagorean Theorem to compute c^2
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

Normally, I’m of the belief that your code should be primarily self-documenting. That said, an inline comment here and there can be helpful for future readers—including yourself.

Block Comments Using Inline Comments

Fun fact: Python doesn’t have block comments. In other words, there is no built-in syntax for handling multiline comments. As a result, PEP 8 recommends using repeated inline comments for block comments:

# Uses the Pythagorean Theorem to compute c^2.
# First, we compute a^2 and b^2. Then, the 
# expression is constructed as a^2 + b^2 and 
# assigned to c^2.
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

Again, these comments are probably excessive; their role is to provide an example of a block comment.

Block Comments Using Multiline Strings

With all that said, it’s possible to simulate block comments with multiline strings:

"""
Uses the Pythagorean Theorem to compute c^2.
First, we compute a^2 and b^2. Then, the 
expression is constructed as a^2 + b^2 and 
assigned to c^2.
"""
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

Now, that looks a little cleaner to me. In addition, it’s a bit easier to manage in source code in my opinion.

That said, keep in mind that this isn’t a true comment. We’ve instead created a string constant which isn’t assigned to a variable. In practice, this isn’t really an issue as the strings will get optimized out in the bytecode.

Another word of caution: sometimes this style of comment can be interpreted as a docstring. For example, if we insert this comment just below a function header, we’ll have created a docstring for documentation purposes:

def pythagorean_theorem(a, b):
  """
  Computes the length of the squared third leg of a right triangle.
  """
  a_squared = a**2
  b_squared = b**2
  c_squared = a_squared + b_squared
  return c_squared

In this example, our multiline comment is actually a docstring which we can use to document the method:

def pythagorean_theorem(a, b):
  """
  Computes the length of the squared third leg of a right triangle.
  :param a: the length of the first leg of the triangle
  :param b: the length of the second leg of the triangle
  :return: a^2 + b^2
  """
  a_squared = a**2
  b_squared = b**2
  c_squared = a_squared + b_squared
  return c_squared

Then, this docstring becomes a runtime attribute of the function. In other words, we can inspect that attribute as follows:

1	`print(pythagorean_theorem.__doc__)`

As you can see, docstrings aren’t like comments in the sense that docstrings still exist at runtime—regular comments do not. Many IDEs and other tools can then extract these docstrings for documentation purposes. How cool is that?

Challenge

At this point, I’d usually measure performance, but I didn’t feel like that would be applicable. Instead, let’s jump straight to the challenge!

Now that we know three different ways to comment code in Python, let’s talk about good commenting practices. In the comments below, share at least one tip you recommend when it comes to commenting code. Feel free to share anything from commenting styles to commenting etiquette. Bonus points for anything that’s Python specific.

As always, I’ll share my own tip below as well! If possible, I’d love to get a little discussion going. Depending on how it goes, I might compile the results in another article.

A Little Recap

And with that, we’re all done. As always, here’s a little recap of our three ways to comment Python code:

# Here is an inline comment in Python
 
# Here
# is
# a
# multiline
# comment
# in
# Python
 
"""
Here is another multiline comment in Python.
This is sometimes interpretted as a docstring,
so be careful where you put these.
"""