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:
- 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:
- Name your variables in such a way that it’s abundantly clear what they contain. E.g., don’t name your list
- Name your 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.
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.
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 not specific multi-line comment form, as is the case in C-like languages.
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.
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.
- 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