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.
Table of contents
What is a Python comment?
Let’s start by defining what a comment is exactly:
- 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!
Comment out code
A pattern that programmers use a lot, is commenting out code temporarily. There are countless reasons why one might want to do this. Here are just a couple of examples:
- A piece of functionality is not working right now, but you plan to work on it later so you don’t want to throw it away
- There’s an alternative piece of code that you might want to use later on, so you leave it as a hint in a comment
- You’re refactoring your code, meaning you’re cleaning up your the code. Often, this is a process where you create more and smaller functions, while you’re not completely ready to throw away the old code.
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 too 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’s 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:
- Name your Python variables in such a way that it’s abundantly clear what they contain. E.g., don’t name your list just
m_list, but instead, call it something like
- Name your Python functions in a concise way that clearly describes what they do.
- Create short functions that only do one thing. If they do more than one thing, split them up into multiple functions. Short functions are also better once you start using unit tests.
Stating the obvious
Many beginning programmers 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:
# Ask for the user's name name = input('Name: ') # Call the say_hi function say_hi(name) # Now we divide the user input by 100 result = input / 100
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.
Commenting out code instead of removing it
As stated above, sometimes you need to comment out code. But that doesn’t mean you can just leave it there. In my professional life as a programmer, I’ve seen way too many commented-out sections of code. The problem with this is that nobody dares to touch it. Your colleague must have left it there for a reason, right?
No… your colleague probably just forgot about it. But can you be sure? For this reason, make a habit of cleaning up code that is commented out.
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.
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.
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 no specific multi-line comment form, as is the case in C-like languages.
Limit the number of comments to the absolute minimum. You should prefer self-documenting code, by using logical names for variables and functions and creating small, understandable functions.
A comment starts with a hash symbol and is ignored by the Python interpreter. A Python 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.