Python: Comments vs Docstrings

Comments in Python improve the readability of the program, it explains the code in a language that is easy to understand whereas docstrings describe what the code does, it does not explain how the code works. In this tutorial, we will understand how docstrings are different from comments in Python.

Here’s a quick summary of the difference between comments and docstrings in Python:

Comments help all programmers (including us) understand the code in simple language.

Docstrings in Python are written mainly for other programmers to know what the imported module, class, or function does.

For instance, consider the following python module:

'''
File-name: mymodule.py
Functions: greet(name)
'''
def greet(name=None):
    '''This method greets a person.
    Parameters:
        name (string): name of the person
    '''
    #before greeting check if name is not null
    if name is not None:
        print('Hello!', name)
    else:
        print('Welcome!')

The code here has both docstrings and comments defined in it.

The comment here will help us to easily understand and edit the source code, while docstrings will be helpful for others in knowing about the module and function when it is imported and used in the shell.

>>> import mymodule
>>> help(mymodule)
File-name: mymodule.py
Functions: greet(name)
>>> help(greet.name)
This method greets a person.
Parameters:
    name (string): name of the person
>>> greet('Pencil Programmer')
Hello! Pencil Programmer

Unlike docstrings, we cannot access comments from the Python shell but can only see them in the source code.

Difference between multi-line Docstrings and Comments

It is not mandatory to write a docstring using triple quotes, if it is one-line, we can write a docstring using the single quote.

Since the string literals written using triple quotes easily expands to multiple lines, they are preferred for writing docstrings in Python.

Whereas, to write multi-line comments in Python, we need to write a number of single-line comments using the hash (#) character.

#First assign value to the name variable
#Then, print using the print() method
name = "AK"
print(name)

Python has no mechanism for writing multi-line comments. Although sometimes we use triple quotes to expand comments on multiple lines, it is not actually considered as a comment by the interpreter but is treated as an unassigned string literal and gets garbage collected.