Geekflare is supported by our audience. We may earn affiliate commissions from buying links on this site.
In Development Last updated: September 8, 2023
Share on:
Invicti Web Application Security Scanner – the only solution that delivers automatic verification of vulnerabilities with Proof-Based Scanning™.

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.

Role of Comments in Programming Languages

Python comments best practices

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 add 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.

How do Comments Enhance the Code Readability?

Python docstring best practices
  • 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.

How to Write Comments in Python?

Docstring comments in Python

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.

Different types of Python Comments


There are three main types.

#1. Single-line Comments

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.

#2. Multi-line Comments

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. """

Best Practices for Writing Comments 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

Best Code Editors to Manage Comments

#1. Visual Studio Code Editor

Python multiline comments

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

How to comment multiple lines in 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++

types of python comments

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

best Python IDEs

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.


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.

  • Srujana Maddula
    Srujana is a freelance tech writer with the four-year degree in Computer Science. Writing about various topics, including data science, cloud computing, development, programming, security, and many others comes naturally to her. She… read more
  • Narendra Mohan Mittal

    Narendra Mohan Mittal is a Senior Digital Branding Strategist and Content Editor with over 12 years of versatile experience. He holds an M-Tech (Gold Medalist) and B-Tech (Gold Medalist) in Computer Science & Engineering.

    read more
Thanks to our Sponsors
More great readings on Development
Power Your Business
Some of the tools and services to help your business grow.
  • Invicti uses the Proof-Based Scanning™ to automatically verify the identified vulnerabilities and generate actionable results within just hours.
    Try Invicti
  • Web scraping, residential proxy, proxy manager, web unlocker, search engine crawler, and all you need to collect web data.
    Try Brightdata
  • is an all-in-one work OS to help you manage projects, tasks, work, sales, CRM, operations, workflows, and more.
    Try Monday
  • Intruder is an online vulnerability scanner that finds cyber security weaknesses in your infrastructure, to avoid costly data breaches.
    Try Intruder