Note that the text in this lesson refers to function definitions, which is a topic you haven’t covered yet in this course. You can come back to this lesson after you learn about functions to review the section about functions.
This text is part of a Real Python tutorial by Jaya Zhané.
When writing code in Python, it’s important to make sure that your code can be easily understood by others. Giving variables descriptive 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 lesson, 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
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.
