Python 3.2 - Comments in Python

 

Comments

Comments are always used for programmer’s convenience in any programming language. A comment is used to describe the features of a program. When we write program then we can write comments for classes, functions, statements etc. Comments help to understand the code easily. For example, you are working in a software company. You wrote a program of ten thousand lines. After some time, you left the job and a new programmer joined the company. Now the new programmer opens the file which you had written. So before proceeding he has to understand the code first so that he can continue. Now, if you used proper comments in your program then the new guy can understand it very easily and it will take very less time. But if you did not use proper comments in your program then the new programmer will have a lot of difficulties understanding what and why you have written this. So it will waste the time because the new programmer has to understand the whole lengthy code of 10000 lines on his own.  

Comments can also help programmers to find errors in large programs. if there is any error occurs in a large program (let say thousands of lines), then programmer can try to find the error with the help of comments in less efforts. It will take more time to find that where is the error in the code, if programmer had not used comments since he has to read the entire code line by line. So it is a good programming practise that you always use proper comments in your program for your convenience. Comments are ignored by Python compiler and PVM and not get executed.

Python has two types of comments – single line comment and multi-line comment

1.   Single line comment

A single line comment starts with the symbol (#). A ‘#’ denotes that this line is a comment and should not be executed by Python. Single line comment should be used when we just have to comment a single line. See Figure 2.6 where we started our program with a comment “# A simple Python program to add two numbers”. So this line is a comment for us to understand that what the program is doing. Python will simply ignore it and will start executing from next line. So you can create a single line comment with symbol (#) for ex –

x = 10 # store 10 into x

y = 20 # store 20 into y

2.  Multi line comments

We can also create multi line comments that will span multiple lines. Triple double quotes (“””) or triple single quotes (‘’’) are used to create multi line or block comments. We must write quotes (“”” or ‘’’) at the beginning and ending of the comment. If there are many comments in our program, then creating single line comments is very tedious job so we can use multi line comments instead. For example –

# a program to add two numbers

# first store 2 integer numbers

# store 5 into x and 10 into y

# add x and y and store into z

x=5

y=10

z= x + y

 

As you can see we want to write many comments at same place, so using # symbol will be very tedious job so we can use multi line comments instead, like this –

 

“”” a program to add two numbers

first store 2 integer numbers

store 5 into x and 10 into y

add x and y and store into z “””

x=5

y=10

z= x + y

Python has no multi line comments

Actually Python has no multi line comments. It only supports single line comment. Triple double quotes or triple single quotes are normal strings that can span multiple lines. If we assign these strings to any variable, then memory will be allocated to these strings internally and will not be considered as multi line comments. And if we don’t assign these strings to any variable, then it will be removed from memory by Garbage Collector (it is a program/module that removes the object from memory when the object is no more required in program) and can be used as comments. But in this case, it will waste time of interpreter.

So using “”” or ‘’’ as comments is not recommended by Python developer team since they internally occupy memory and would waste time of interpreter since interpreter has to check them.

Let’s take an example –

'''

    If you use this style for comment. Then, first this comment will

    internally occupy space in memory.

    When we execute this program, Interpreter will find

    that this comment is not assigned to any variable. Then

    Interpreter will remove it from memory and would treat it as

    a comment. But it wasted time of Interpreter. '''

str = '''

    You can use this style to store large strings into variables.

    This will occupy space in memory.

    When we execute this program, Interpreter will find

    that this string is assigned to a variable. So

    Interpreter will not remove it from memory and would treat it as

    a string. So this is not a comment anymore since it is assigned

    to a variable.'''

print(str) 

# So never use """ or ''' to create comments because it will

# internally occupy space in memory and waste the time of Interpreter.

# Always use '#' to create comments.

 

Output –

    You can use this style to store large strings into variables.

    This will occupy space in memory.

    When we execute this program, Interpreter will find

    that this string is assigned to a variable. So

    Interpreter will not remove it from memory and would treat it as

    a string. So this is not a comment anymore since it is assigned

    to a variable.

Docstrings

When we write strings inside “”” or ‘’’ and if these strings are written as the first statement in a function, class or method, then these strings are called Docstrings or documentation strings. Docstrings are used to create API (application programming interface) files. An API file is a simple text or html file that is created by developers at the time of software/application development. An API file contains information or features of classes, functions, methods of the software so that end user or customer can understand the software easily. We can create API files for our customers to describe how and what the software will work.