Why we need comments in Python

Comments are the statements which are included in the source code but don’t contribute to program logic. A python comment is not executed by the interpreter and it can only be accessed when we have access to the source code. Now the question is that despite the fact that they do not contribute to the program logic, why are the comments included in the source code. In this article we will try to see why we need comments in python. Let’s dive into it then.

We use comments to specify the metadata of the source code.  

When we write any computer program for commercial purposes, We generally include the name of the programmer, date and time at which the source code was created. Generally when a program is developed under contract, the conditions for use of the source code and the license and copyright of the source code and a general description of the program  is also included in the source file. To include this information in the source code, we use python comments. Metadata is included in the header comment in the start of the source code file. Following is an example of a header comment.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Created on Sat Mar 27 19:59:11 2021

@author: aditya1117
This code has been written to demonstrate the use of comments in python to specify metadata of the sorce code
"""

When anyone accesses the source code file, they can read the metadata of the file and then they can know if they are allowed to reuse or modify the source code or not. If any changes are made to the source code,they should also be mentioned in the metadata so that others can get the information about that.

We use comments for documentation of the source code.

For documentation of source code, we use comments to describe specification of each function and method used in the program. We include the input parameters, expected output  and  a general description of the method or function so that when someone tries to use the functions and methods in the program, he can get the idea from the documentation. When a framework or library is introduced in any programming language, proper  documentation of the source code has to be provided. Following is an example of documentation describing a function which adds a number and its square to a python dictionary as key value pair.

#The function adds a number and its square to a python dictionary as key value pair.
def add_square_to_dict(x,mydict):
    a=x*x
    mydict[str(x)]=a
    return mydict
    

We use comments to clarify why a specific statement has been written in the source code.

Generally the functions and statements used in the program should be self explanatory about their use in the program but whenever it doesn’t seem obvious why any statement has been written in the source code, we need comments to specify why the statement has been written there in the source code. 

We use comments to specify the instructions which help in debugging the code and improving functionalities in the program.

When a program is written, many modifications are made to the code according to the functionalities needed in the code. To be able to refactor and modify the code for improvements, a programmer must know all the properties of the functions, methods, classes etc  included in the source code. The programmer must clearly understand each statement included in the code to be able to modify it. To provide all this information to the programmer, we need comments to specify all the properties of the functions and methods in the source code.

We use comments for specifying the changes made to the source code.

Whenever any change is made to the source code of the program,it must be specified in the source code using comments and should include information about why the changes were made,and who made the changes.

Conclusion

In this article, we have seen various reasons why we need comments in python. Stay tuned for more informative articles.