How to Write Comments in Python for Clean and Readable Code

Writing good comments in Python will allow other developers and testers to read and understand your code easily.

Clean code with consistent syntax, descriptive variable naming, and indentation is like the first book, easier to understand and maintain.

Plus, these days, it’s less common for an individual to write the complete code for the entire application or software; rather, a team or group of people will be working towards the same goal. In this case, clean and readable code makes collaboration simpler and more efficient.

Developers and testers always aim to deploy bug-free software to production. Writing clean and readable code accelerates this process by making debugging simpler and more accurate. Though you find some errors in the production, cleaner code is easier to update.

More importantly, clean and readable code lives longer because the code stays fresh as time goes on.

Finally, it’s crucial to have clean and readable code to create long-lasting software. But the question is, how do we exactly achieve that? Well, one method is using Comments.

Isn’t it frustrating when you’ve written the entire code for a complex logic, but the next day, when you can’t pick up where you left off? This doesn’t happen when you write comments.

Comments are a human language explaining what the source code is doing. You can write them in any language, preferably English, since it’s a global language.

So, whenever you get back to your source code after days or even years, the comments will explain to you what you once wrote.

Also, they help other developers to easily understand your code. That’s why the code written with comments stays forever, even in the absence of its author.

Moreover, it’s pretty common to have conflicts when dealing with different programming languages, especially when you are working in a team. That’s where comments come to the rescue. Though you don’t know the programming language of the source code written by your teammate, comments help you understand the logic behind it.

Code documentation is a more comprehensive way to maintain your source code and lets your team seamlessly collaborate. It contains everything about the code, like the design, functionality, architecture, components, etc.,

Comments even contribute to this code documentation. Well-written comments can be directly taken into code documentation so that developers not only get the what and why but also the how of your code.

• Comments don’t just read out the code but also help you understand the developer’s intent behind each line. So if you find some bug in the future, you’ll know where to exactly make the code updates.
• You can write comments as a paragraph for the entire code or individual lines explaining what each code block does. This way, they let you and other developers understand the code well, enhancing readability.
• Comments can divide the code into logical sections, making code navigation simpler.
• You should include comments detailing expected inputs, outputs, and use cases so that a tester can read your code.
• Finally, putting well-written comments in your documentation improves the overall readability of code documentation.

Comments in Python begin with a hash (#) symbol. So, when you start a line with hash (#), then anything written in that line is treated as a comment.

When you run the code, the compiler ignores the line starting with hash (#) like it doesn’t even exist. However, the comments remain visible in the source code to serve their purpose.

There are three main types.

These are the ones that you have seen above. They start with the hash (#) symbol. Basically, the line starting with the hash (#) symbol is dedicated to the comment. So, This is called a single-line comment, where you can write a comment only in one line starting with hash (#).

Here is how you can write single-line comments

# This is single line comment.

Technically, Python doesn’t support multiline comments, but there are ways to achieve this in Python.

You can use hash (#) to write multi-line comments as well. Every line you write should start with a hash (#) symbol here.

# This is the first comment.
# This is second comment.
# This is the last comment.

#3. Python Docstrings

A popular way to write multiline comments is to use string literals – “””….”””. When you write something in between triple quotes, the Python compiler ignores those lines and executes the remaining part in the file.

These comments are called docstrings when written right after the functions, modules, and classes.

Here is the syntax to do this

""" Multi-line comments using docstrings 
in Python. """

Writing clear and detailed comments improves your code readability and maintenance. So, here are the best practices for clear commenting in Python.

Comments shouldn’t just narrate what the code is doing, instead, they should reflect the purpose and intent behind each line.

Remove outdated comments, and make sure to update comments whenever you modify the code.

Instead of long stories, write short and on-point comments.

Bad example: The function takes a,b as input, calculates a   b, and returns the value.
Good example: The function returns the sum of a and b.

Using meaningful and descriptive names for variables and function names can eliminate redundant comments.

Code first? Or comment first? Commenting before coding is the best practice; that is, write your comments and then the corresponding code. This way, you can first think of the logic and then convert it to code.

# Returns true if the cnt is less than 1.
return cnt < 1

Use a consistent commenting format like spacing, indentation, type of comments, etc., for the entire code. This will be less confusing and more organized for readers.

Use docstrings to explain functions and classes in Python as shown in the following example.

def add_num(a,b):
    """ this function returns the sum of a and b """
    sum = a b
    return sum

Avoid unnecessary comments in your code. For example, the following line of code doesn’t need a comment to understand it.

ans = 42

#1. Visual Studio Code Editor

Visual Studio Code Editor is the best IDE built by Microsoft for a complete development environment. With native support for Node.js and JavaScript, the tool also supports many other programming languages seamlessly.

This highly customizable tool has various extensions for different functionalities. ‘Better Comments’ is one such extension that lets you create human-friendly comments.

You can categorize your comments into alerts, queries, highlights, etc., for easier navigation.

VS code supports multi-cursor editing so that you can comment or edit multiple lines simultaneously.

This editor is available on all major platforms like Mac, Windows, and Linux.

#2. Sublime Text

Sublime Text is the go-to editor for big projects and heavy coding. The editor is known for its speed, customization, and shortcuts.

The tool’s powerful syntax highlighting feature helps you easily distinguish between the code and comments.

Like VS code, Sublime text also supports multi-cursor editing for commenting multiple lines at the same time.

Thanks to its autocomplete feature. You don’t need to manually repeat the code lines; this feature auto-completes your code based on the patterns, helping you code faster.

Moreover, the tool’s ‘Goto Anything’ feature lets you switch between the functions and files of your project seamlessly.

#3. Notepad

Nodepad is a popular and simple text editor written in C and supports numerous programming languages. It doesn’t look like a modern editor like VS Code or Sublime Text; its interface is very plain and looks like it does what it needs to.

Nodepad offers numerous standard shortcuts for efficient commenting. You can also customize the shortcut keyboard to personalize your commenting experience.

Its document map feature shows you the overview of the project structure, letting you navigate over the files, folders, and code seamlessly.

#4. Vim

Vim IDE provides faster development and code execution. Everything and anything can be done on this editor using keyboard shortcuts, so you should put some serious effort into mastering it.

This keyboard-centric editor also offers many commenting features via keyboard shortcuts. It has powerful features and commands to effectively navigate over comments.

This lightweight software can handle huge files and hundreds of programming languages. Who hates free stuff? Like all the editors in the list, Vim is also completely free and open source.

It comes native in macOS and Linux systems and is downloadable on Windows.

#5. PyCharm

PyCharm is a powerful IDE that is specially designed for Python development. Though it supports many other programming languages, it works best for Python. It has code completion, syntax highlight, and debugging features tailored to Python.

Moreover, it makes commenting in Python much more efficient. It provides navigation features to help you jump to specific comments easily.

Get various comment templates and create custom comment templates efficiently in Pycharm.

Also, the editor’s refactoring tools let you easily update or fix comments.

Conclusion

Following code standards is necessary throughout the entire code development process and mandatory to write production-ready code, as your code should be readable by all other developers and testers.

One important practice to create a readable code is by writing comments. Comments are available in almost all programming languages. However, with this article, you should now know how to write Python comments, their types, and the best practices to follow while writing comments.

Also, the best code editors that help you in comment management are listed down.