Writing sophisticated Python code is a skill every programmer should be proud of – but it's not the only skill that makes a programmer skillful. To consider a program well-written, it's necessary that it be understood by other programmers who read it.
This can be done by naming variables well, defining explicit functions, and keeping code organized. But the most effective way to ensure that your code is easily understood is to write comments.
In this brief guide, we'll cover all you need to know about writing comments in Python.
Why is Commenting Important?
Comments appear as in-line explanations and also module-level docstrings, but regardless of how they are included, they are integral parts of any program. They help explain the complexities of the program.
To understand why commenting is important, let's consider both scenarios of when comments can be useful – when you read your code (perhaps much later) and when others read your code.
Scenario #1: When You Read Your Code
Let's say Jackson, a client, demands a last-minute deployment for their web service. The deadline is close, so you decide to oblige, concluding that the code needs to be written ASAP and the comments and documentation can be handled later.
You put in your full effort and are able to meet Jackson's demands by the deadline. This is great.
You stick to your decision of adding the comments at a later time. But as soon as this deadline is met, your boss walks in, hands you a new project, and asks you to begin working on it immediately. You forget to put the commenting task on your to-do list.
A few days pass, and the commenting task remains undone. The task of going back to comment the code has completely slipped your mind. But there's nothing to worry about, right?
Fast forward a few months, and Jackson's back with a new request. He wants you to build a new patch for the service you developed and meet some new requirements.
Now, since you built it, you're handed Jackson's work. It only makes sense for the developer to maintain it. You launch your IDE and open the file, and you have no idea how you made things work. And you have no comments to guide you, either.
So, you do what any developer would. You spend hours going through your old code, but the more you look into it, the more confused you get. Jackson's previous deadline put you in such a rush that you didn't think to name the variables relevant to what you wanted to accomplish with them.
Worse, the functions are not in the right control flow. Without any comments, you're completely in the blind as to how your script is working.
It's normal for a developer to forget what they wrote. This is especially true for projects that the developer worked on a long time ago or was under pressure when they worked on it.
The latter case can be stressful since developers spend hours in front of their computers when the deadline is right around the corner. Their hands are cramped, eyes bloodshot, and code messy.
By the time the project is completed and handed to the client, the developers are exhausted. Going back and commenting the code is not possible at that stage. And this backfires later since they often spend a lot of time parsing through what they wrote earlier to understand the program.
Taking the time to write comments during development can save you the head-hurting task of understanding the code without any explanation later on.
Scenario #2: When Others are Reading Your Code
Let's picture a different scenario. Let's say you're the sole developer on a Django project. You understand your code inside and out, so you don't find the need to write any comments or document your code.
In fact, this is how you prefer it since writing and maintaining comments takes time and effort. You don't see why it's necessary for you. But here's the issue:
You work on this project for a year, transforming it from a small Django side project to a project with 20,000 lines of code. Now, your supervisor decides to hire more developers to help maintain it.
Your new coworkers work night and day to understand how the project works. But within a few days of working together, you realize they're having trouble understanding your code. Besides the quirky variable names, your syntax is non-conventional.
Because of this, the new developers go over your code line-by-line. It takes a week before they can help you maintain it.
Leaving comments throughout your programs ensures that any developer looking at your code can understand how it works. Plus, they remove the need for developers to go through the code line-by-line. The code becomes a lot easier to make sense of, and developers can quickly skim through it.
Commenting on every project you work on right from the outset ensures a smooth transition for the developers that work on it after you.
How to Write Comments in Python
Developers use comments to describe the code. They are usually put in parts of the code where it gets complicated to help other developers understand it. To write a comment, you put a pound sign before the text. It's as simple as that.
# This is what a comment looks like
When you use a pound sign, Python ignores everything that comes after it till the end of that line. So, you can insert comments anywhere in your code, including in lines that have code.
print("This will print") # This won't print
Comments must be brief and to the point. According to Python Enhancement Proposal 8, the code Python programmers write must be a maximum of 79 characters per line.
The proposal also recommends that programmers write comments that are 72 characters maximum – whether they are docstrings or inline comments.
So, if your comment is long, you must split it into two or more lines as required.
If you have experience with Java, Go, or C, you will know that writing a multiline comment is as simple as putting a pound sign and writing whatever you want. But this is not how Python does it.
# Writing comments this way won't work in Python
Python will pass the first line off as a comment. However, the next two lines will throw a syntax error.
In Java, you can write a multiline comment by putting your text between /* and */ like so:
/* This is what a multiline comment looks like in Java */
What you might find surprising is that Python doesn't support multiline comments natively. However, creating multiline comments in Python is easy, and there are two ways to do it.
One way to do it is to write a comment line, then hit Enter, add another pound sign, and write another line. Here's what this looks like:
# This is how # you can spread Python comments # over several lines
So, the way Python processes comments remain the same in the example above. It ignores everything after the pound sign.
The second way to approach commenting is to put three double quotes around the text you have written as a comment. Here's what that looks like:
""" If you prefer not entering pound signs multiple times you can write your comment this way """
If you've worked with Java, you might recognize this method. Java also processes the text in the middle of triple quotes as comments.
Bear in mind that though using triple quotes this way gives you a multiline functionality, the example above is technically not a comment. It's simply a string that isn't assigned to any variable.
For this reason, it's ignored when you run your program runs and doesn't appear in the bytecode. It is effectively a comment, but not technically.
There is no inherent harm in writing comments this way. However, you must carefully place these multiline comments since they can turn into docstrings depending on where you place them. A docstring is a piece of documentation associated with a method.
So, if you write a multiline comment in this way right after defining a function, the comment will turn into a docstring for the object.
If you aren't sure which format you should use in a situation, it's best for you to rely on the pound signs.