Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Writing Comments in Python
When writing code in Python, it’s important to make sure that your code can be easily understood by others. Giving variables obvious names, defining explicit functions, and organizing your code are all great ways to do this.
Another awesome and easy way to increase the readability of your code is by using comments!
In this tutorial, you’ll cover some of the basics of writing comments in Python. You’ll learn how to write comments that are clean and concise, and when you might not need to write any comments at all.
You’ll also learn:
- Why it’s so important to comment your code
- Best practices for writing comments in Python
- Types of comments you might want to avoid
- How to practice writing cleaner comments
Free Bonus: 5 Thoughts On Python Mastery, a free course for Python developers that shows you the roadmap and the mindset you’ll need to take your Python skills to the next level.
Why Commenting Your Code Is So Important
Comments are an integral part of any program. They can come in the form of module-level docstrings, or even inline explanations that help shed light on a complex function.
Before diving into the different types of comments, let’s take a closer look at why commenting your code is so important.
Consider the following two scenarios in which a programmer decided not to comment their code.
When Reading Your Own Code
Client A wants a last-minute deployment for their web service. You’re already on a tight deadline, so you decide to just make it work. All that “extra” stuff—documentation, proper commenting, and so forth—you’ll add that later.
The deadline comes, and you deploy the service, right on time. Whew!
You make a mental note to go back and update the comments, but before you can put it on your to-do list, your boss comes over with a new project that you need to get started on immediately. Within a few days, you’ve completely forgotten that you were supposed to go back and properly comment the code you wrote for Client A.
Fast forward six months, and Client A needs a patch built for that same service to comply with some new requirements. It’s your job to maintain it, since you were the one who built it in the first place. You open up your text editor and…
What did you even write?!
You spend hours parsing through your old code, but you’re completely lost in the mess. You were in such a rush at the time that you didn’t name your variables properly or even set your functions up in the proper control flow. Worst of all, you don’t have any comments in the script to tell you what’s what!
Developers forget what their own code does all the time, especially if it was written a long time ago or under a lot of pressure. When a deadline is fast approaching, and hours in front of the computer have led to bloodshot eyes and cramped hands, that pressure can be reflected in the form of code that is messier than usual.
Once the project is submitted, many developers are simply too tired to go back and comment their code. When it’s time to revisit it later down the line, they can spend hours trying to parse through what they wrote.
Writing comments as you go is a great way to prevent the above scenario from happening. Be nice to Future You!
When Others Are Reading Your Code
Imagine you’re the only developer working on a small Django project. You understand your own code pretty well, so you don’t tend to use comments or any other sort of documentation, and you like it that way. Comments take time to write and maintain, and you just don’t see the point.
The only problem is, by the end of the year your “small Django project” has turned into a “20,000 lines of code” project, and your supervisor is bringing on additional developers to help maintain it.
The new devs work hard to quickly get up to speed, but within the first few days of working together, you’ve realized that they’re having some trouble. You used some quirky variable names and wrote with super terse syntax. The new hires spend a lot of time stepping through your code line by line, trying to figure out how it all works. It takes a few days before they can even help you maintain it!
Using comments throughout your code can help other developers in situations like this one. Comments help other devs skim through your code and gain an understanding of how it all works very quickly. You can help ensure a smooth transition by choosing to comment your code from the outset of a project.
How to Write Comments in Python
Now that you understand why it’s so important to comment your code, let’s go over some basics so you know how to do it properly.
Python Commenting Basics
Comments are for developers. They describe parts of the code where necessary to facilitate the understanding of programmers, including yourself.
To write a comment in Python, simply put the hash mark # before your desired comment:
# This is a comment
Python ignores everything after the hash mark and up to the end of the line. You can insert them anywhere in your code, even inline with other code:
print("This will run.") # This won't run
When you run the above code, you will only see the output This will run. Everything else is ignored.
Comments should be short, sweet, and to the point. While PEP 8 advises keeping code at 79 characters or fewer per line, it suggests a max of 72 characters for inline comments and docstrings. If your comment is approaching or exceeding that length, then you’ll want to spread it out over multiple lines.
Python Multiline Comments
Unfortunately, Python doesn’t have a way to write multiline comments as you can in languages such as C, Java, and Go:
# So you can't
just do this
in python
In the above example, the first line will be ignored by the program, but the other lines will raise a Syntax Error.
In contrast, a language like Java will allow you to spread a comment out over multiple lines quite easily:
/* You can easily
write multiline
comments in Java */
Everything between /* and */ is ignored by the program.
While Python doesn’t have native multiline commenting functionality, you can create multiline comments in Python. There are two simple ways to do so.
The first way is simply by pressing the return key after each line, adding a new hash mark and continuing your comment from there:
def multiline_example():
# This is a pretty good example
# of how you can spread comments
# over multiple lines in Python
Each line that starts with a hash mark will be ignored by the program.
Another thing you can do is use multiline strings by wrapping your comment inside a set of triple quotes:
"""
If I really hate pressing `enter` and
typing all those hash marks, I could
just do this instead
"""
This is like multiline comments in Java, where everything enclosed in the triple quotes will function as a comment.
While this gives you the multiline functionality, this isn’t technically a comment. It’s a string that’s not assigned to any variable, so it’s not called or referenced by your program. Still, since it’ll be ignored at runtime and won’t appear in the bytecode, it can effectively act as a comment. (You can take a look at this article for proof that these strings won’t show up in the bytecode.)
However, be careful where you place these multiline “comments.” Depending on where they sit in your program, they could turn into docstrings, which are pieces of documentation that are associated with a function or method. If you slip one of these bad boys right after a function definition, then what you intended to be a comment will become associated with that object.
Be careful where you use these, and when in doubt, just put a hash mark on each subsequent line. If you’re interested in learning more about docstrings and how to associate them with modules, classes, and the like, check out our tutorial on Documenting Python Code.
Python Commenting Shortcuts
It can be tedious to type out all those hash marks every time you need to add a comment. So what can you do to speed things up a bit? Here are a few tricks to help you out when commenting.
One of the first things you can do is use multiple cursors. That’s exactly what it sounds like: placing more than one cursor on your screen to accomplish a task. Simply hold down the Ctrl or Cmd key while you left-click, and you should see the blinking lines on your screen:
This is most effective when you need to comment the same thing in several places.
What if you’ve got a long stretch of text that needs to be commented out? Say you don’t want a defined function to run in order to check for a bug. Clicking each and every line to comment it out could take a lot of time! In these cases, you’ll want to toggle comments instead. Simply select the desired code and press Ctrl+/ on PC, or Cmd+/ on Mac:
All the highlighted text will be prepended with a hash mark and ignored by the program.
If your comments are getting too unwieldy, or the comments in a script you’re reading are really long, then your text editor may give you the option to collapse them using the small down arrow on the left-hand side:
Simply click the arrow to hide the comments. This works best with long comments spread out over multiple lines, or docstrings that take up most of the start of a program.
Combining these tips will make commenting your code quick, easy, and painless!