Python Comment: What It Is And How to Create

In this article, you will learn what Python comments are, how to add comments to your Python code, what the common pitfalls are, and how to create docstrings.

What is a Python comment?

Let’s start by defining what a comment is exactly:

Comment
A comment is an explanation in the source code of a Python program. Comments are added with the purpose of making source code easier for humans to understand. They are ignored by the Python interpreter.

So, in short, a comment helps you and other readers of your code to better understand it.

Create a single-line Python comment

In Python, we create a comment by starting the line with the hash symbol: #. This symbol is known as the number sign, hash, or (in North American usage) pound sign. Whatever you call it, this is what it looks like:

# This is a single-line comment in Python

# And here's another one!

Multiline Python comment

There’s no special way to add multi-line comments, also called block comments. Instead, you simply use the hash sign at the start of each line, like so:

# This is a multi-line comment in Python,
# there's not much difference with single-
# line comments, as you can see!

In Python (or any language, for that matter), it’s better to write clear, understandable code. So if you’re doing well, you should not need multi-line comments that often!

Common mistakes with Python comments

There are a few mistakes that many programmers make when it comes to comments. Therefore, let’s explore these, so you hopefully won’t make them!

Using to many comments

You should limit the use of comments to what is absolutely necessary. Why is that?

There’s a concept called self-documenting code. This means that your code is so readable and easy to understand that comments or documentation are hardly needed. If your code is readable and you don’t need comments, it more compact and easier to read. Hence, it would be best if you always strived to write self-documenting code and only resort to comments to explain the more advanced or non-obvious things.

Writing self-documenting code deserves its own article, but there are three key takeaways that already can help a lot:

  1. Name your variables in such a way that it’s abundantly clear what they contain. E.g., don’t name your list m_list, but member_list.
  2. Name your functions in a concise way that clearly describes what they do.
  3. Create short functions that only do one thing. If they do more than one thing, split them up into multiple functions.

Stating the obvious

Many beginners tend to state the obvious. In other words, they describe in comments what they are about to do. You too might be tempted to do so, especially when a language is new to you, as a note to yourself.

Here are some examples of stating the obvious:

# Create a list of weekdays
days = ['Monday', 'Tuesday', ...]

# Now we divide the user input by 100
result = input / 100

# Create a new car class
car = Car(color='black', num_wheels=4)

Not maintaining your Python comments

While editing your code, it’s easy to forget the comments that are there. Always check if they still apply or perhaps need a touch-up because you just changed the code.

It’s a common mistake to forget comments that describe a function or a class because they are often not very close to the code you’re editing. After refactoring your code, always take a look at the comments.

Frequently asked questions about Python comments

Here are a couple of frequently asked questions about Python comments. They are covered above already, but they are here for those that are looking for quick answers.

How do I comment out a single-line of Python code?

Use the symbol # at the start of a line to create a Python comment. This symbol is known as the number sign, hash, or (in North American usage) pound sign.

How do I comment out multiple lines of Python code?

Use the symbol # at the start of each line to create a multi-line Python comment. This symbol is known as the number sign, hash, or (in North American usage) pound sign. There is not specific multi-line comment form, as is the case in C-like languages.

How many comments should I use?

Limit to number of comments to the absolute minimum. You should prefer self-documenting code, by using logical names for variable and functions, and create small, understandable functions.

What is the difference between an comment and a docstring?

A comment start with a hash symbol and is ignored by the Python interpreter. A docstring is an actual string, that documents your module, class, function, or method. Because it’s not assigned to anything, it’s ignored when your code runs.

Docstrings: document your code with strings

Docstrings allow you to document your code more formally. They are described in detail in PEP-0257, but I’ll tell you all you need to know in this section.

Let’s start by defining what a docstring is. This is taken straight for the PEP mentioned above.

Docstring
A docstring is a string that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

There’s a clear distinction between comments and docstrings. A comment is ignored completely by the Python interpreter, while a docstring is an actual string that the interpreter sees. Because we don’t assign the string, it’s considered useless by the interpreter and is ignored. The effect, in short, is the same: it’s a piece of text that documents your code.

How to create docstrings

As defined above, we can simple insert a string as the first statement of any module, function, class, or method and it becomes the docstring. Here’s an example of how to document a Python class and its functions using docstrings:

class MyDocumentedClass:
    """This class is well documented but doesn't do anything special."""

    def do_nothing(self):
        """This method doesn't do anything but feel free to call it anyway."""
        pass

As you can see, I created these strings with triple quotes. It’s for a reason: they are more recognizable as a docstring, and it’s easier to expand them to multi-line strings later on (if needed).

How to read docstrings

The docstring is internally assigned to the __doc__ special attribute. Usually, you don’t access it that way.

When you call help(MyDocumentedClass) in a Python REPL, you can best see the result of these docstrings:

Help on class MyDocumentedClass in module __main__:

class MyDocumentedClass(builtins.object)
 |  This class is well documented but doesn't do anything special
 |
 |  Methods defined here:
 |
 |  do_nothing(self)
 |      This method doesn't do anything but feel free to call it anyway

Please help us and share this article

About the author

Erik is the owner of Python Land and the author of many of the articles and tutorials on this website. He's been working as a professional software developer for 25 years, and he holds a Master of Science degree in computer science. His favorite language of choice: Python!