Python Multiline Comments [Methods & Examples]


Python

Author: Bashir Alam
Reviewer: Deepak Prasad

Python comments are the most useful information that the developers can provide to make the reader understand the source code. It explains the logic or a part of it used in the code. Comments are useful to someone maintaining, enhancing, or using our code when we are no longer around to help them or if we have a long program comments help us to know each part of our code. In this tutorial we will learn about how we can use comments in our program and will discuss different types of comments. Moreover, we will also cover the docstring along with examples. By the end of this tutorial, you will have a strong command over comments and you will know why it is important to have comments in our program.

 

Getting start with Python comments

Sometimes we may want to document our code. For example, we may want to note what a piece of code does in our program or what a particular function does. To do it, we use the comments. Typically we use comments to explain formulae, algorithms and complex business logics. When we execute a program, the python interpreter ignores all the comments and only interprets the code. In this section we will get started to write comments in our code.

 

What are Python comments?

A python comment is a line of text that appears in a program but is not executed by the program. We can declare a comment in python using a hashtag. Comments can appear on a new line or at the end of an existing line of code. Basically comments are used to explain how code works and for testing purposes. Here is a simple example of a single-line comment in python.

# this line is a comment

We can see the hash mark denotes our comment and everything that we write after the hashtag will be considered part of the comment. And his line will be ignored by the compiler when we will run our code because comments are to be read by humans, not by machines.

The best practice is to add comments at the same indent level as the code to which the comment is referring.

 

Python simple comment

A comment block explains the code that follows it. Typically, we indent a block comment at the same level as the code block is. To create a block comment, we start with a single hash tag followed by a single space and text explaining the code.  See the following example of a simple comment in Python.

# creating variable
Data = 5

Most comments are used to explain complex ideas, formulae, and algorithms. For example see the example below which explains the code.

# incrementing by 5
Data += 5

The best practice is to write comments in the same intended level of code. See the following example.

# outermost for loop
for i in range(4):
   # second for loop
   for k in range(5):
       # innermost for loop
       for l in range(8):
           # increment num by 1
           num +=1

Notice that the intended level of code and comment is the same.

 

Python inline comments

When we place a comment on the same line as the statement, we will have an inline comment at that time. Similar to block comment, an inline comment begins with a single hashtag and is followed by a space and text of comment. Remember to put the inline comment after the code statement, otherwise the code statement will also be treated as a python comment.

See the following simple example of inline comment in Python.

Num = 50  # variable declared

Here python interpreter will only read the code/text that is before the hashtag and any thing after hashtag will be considered to be a comment

Inline comments are important, because unlike comment blocks, they don't take one line and we don't need to be worried about the intended level as well.  Here is another example which shows the usage of inline comments.

for i in range(4): # outermost for loop
   for k in range(5):  # second for loop
       for l in range(8): # innermost for loop
           num +=1 # increment by 1

Notice that this time the code is more readable and it takes less number of lines as well.

 

Python docstrings

A Python docstring is a string which is used to document a python module, function, class or a method, so that programmer or the readers can understand what it does without having to read the details of the implementation. Python docstrings are similar to python comments but not exactly the same. There is some difference between docstring and comment in python. The syntax of python docstrings is not like the comment one. Docstrings in python are written inside triple quotation marks.  See the following example of docstring.

class car:
   '''This class contains all the info about car'''

Like comments, the python docstrings are also ignored by the interpreter.

Docstrings are great for understanding the functionality of the larger part of the code. They are a descriptive text written by a programmer mainly for themselves and others to know what the line of code or expression does.  One more important feature is that we can print out the docstring if we could figure out where it is written in a large program. In python we have a built-in function known as __doc__ which prints out the docstring of the program. See the following example.

class car:
   '''This class contains all the info about car'''
# printing docstring
print(car.__doc__)

Output:

This class contains all the info about car

 

Python multiline comments

Unlike many other programming languages, Python does not have an out of the box multiline commenting syntax. But that doesn't mean we cannot have multiline comments. There are various ways of implementing multi line comments in python. In this section we will discuss two most common types of python multiline commenting.

 

Method-1: Python multiline comment using hashtag

The simplest way of multiline commenting in python is to use consecutive single line comments using a hashtag. See the following example which uses multiline comments by using consecutive single line comments.

# Declaring variable
# name of variable is data
# assigned value of 5 to the variable
Data = 5

In general most python projects and developers follow this style of multiline commenting for Python.

Here is another example which uses multiline and inline comments. See the example below:

# Author : Bashir Alam
# Date : 17/09/2021
# Published : yes

class car:  # created class named car
   def main():   # contains main function
       return  True # Return true

 

Method-2: Python multiline comment using triple quoted string literals

Another way to write proper multiline comments in python is to use multiline docstring. It can either be written using single-triple quotation marks or double-triple quotation marks. See the example below which uses multiple docstings.

class car:
   '''This is car class
   it will have all the functionalities related to cars
   It return true for all cars'''

Or this is also a valid multi line docstring.

class car:
   """This is car class
   it will have all the functionalities related to cars
   It return true for all cars"""

As you can see, we can use triple-quoted strings to create something that resembles a multiline comment in Python. We just make sure that we indent the opening of triple quotation marks correctly, otherwise, we will get syntax errors. For example, see the example below:

class car:
"""This is car class
   it will have all the functionalities related to cars
   It return true for all cars"""

When we run the above code, here is what we get:

Python Multiline Comments [Methods & Examples]

Keep in mind that this technique of using docstring does not create True comments. This simply inserts a text constant that does not do anything. It is the same as inserting a regular single-line string somewhere in your code and never accessing it.

 

Python commenting shortcuts

Sometimes it might be hard and boring to add multiline comments line by line. Or may be difficult if you wanted to comment out a whole section of code. So here are a few tricks and shortcuts that we can use to comment out code.

To comment out a piece of program ( multiline ), simply we need to select the desired code and then press ctrl + / on pc and cmd + / on mac. It should comment out the whole selected program. To remove comments from the whole piece of code, all we need to do is the same process as we did for commenting.

Sometimes too much lengthy multiline comments may look weird. So we can collapse all of them using a small down arrow button on the left-hand side.

Other editors have shortcuts options too. For example atom, VS code and Pycharm have built-in shortcuts for block comments.

 

Summary

In Python comments are written to make users understand the program and make it more readable. Python does not support multiline comments but does have docstring. We can achieve multiline comments in python by writing consecutive single line comments.  Also we can use docstrings as a replacement for multiline comments in python, it can be declared within triple quotation marks. In this tutorial, we learned about python comments using various examples. We also covered some of the shortcuts for creating comments as well.

 

Further Reading Section

Python multiline comments
Guide about docstrings

 

Bashir Alam

Bashir Alam

He is a Computer Science graduate from the University of Central Asia, currently employed as a full-time Machine Learning Engineer at uExel. His expertise lies in Python, Java, Machine Learning, OCR, text extraction, data preprocessing, and predictive models. You can connect with him on his LinkedIn profile.

Can't find what you're searching for? Let us assist you.

Enter your query below, and we'll provide instant results tailored to your needs.

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can send mail to admin@golinuxcloud.com

Thank You for your support!!

2 thoughts on “Python Multiline Comments [Methods & Examples]”

Leave a Comment