Difference between comments and docstrings in Python

Comments are used to increase the readability and understandability of the source code. A python comment may be a single line comment or a multiline comment written using single line comments or multiline string constants. Document strings or docstrings are also multiline string constants in python but they have very specific properties unlike python comment. In this article we will look at the differences between comments and docstrings in python.

Declaration of comments in python

Single line comments in python are declared using a # sign as follows.

#This is a single line comment.

Python does not primarily have multiline comments but we can write multiline comments in python using multiple single line comments as follows. The function given in the example adds a number and its square to a python dictionary as key value pair.

#This is a multiline comment
#written using single line comments
def add_square_to_dict(x,mydict):
    a=x*x
    mydict[str(x)]=a
    return mydict

We can also implement multiline comments in python using multiline string constants as follows. Here the multiline string is declared but isn’t assigned to any variable due to which no memory is allocated for it and it works just like a comment.

"""This is a multiline comment 
written using multiline strings """

We should keep in mind that comments written using # sign need not follow indentation rules but comments written using multiline strings must follow the indentation of the block in which they are declared.

Declaration of Docstrings in python

A docstring is a string constant associated with any python object or module.  The object may be a class, a method or a function. The docstring is written simply like multiline comments using multiline strings but it must be the first statement in the object’s definition. 

A docstring for a class in python is declared as follows.

class MyNumber():
    """This is the docstring of this class.
    
    It describes what this class does and all its attributes."""
    def __init__(self, value):
        self.value=value

A docstring for a method is declared as follows.

class MyNumber():
    """This is the docstring of this class.
    
    It describes what this class does and all its attributes."""
    def __init__(self, value):
        self.value=value
    def increment(self):
        """This is the docstring for this method.
        
        It describes what the method does, what are its calling conventions and
        what are its side effects"""
        self.value=self.value+1
        return self.value

A docstring for a function is declared as follows.

def decrement(number):
    """This is the docstring of this function.
    
    It describes what the function does, what are its calling conventions and
        what are its side effects"""
    number=number-1
    return number

Accessing comments in python

Comments cannot be accessed while execution of a program because they are not associated with any object. Comments can only be accessed when someone has the access to the source code file.

Accessing the Docstrings in python

We can access docstring associated with any python object using its __doc__ attribute as follows.

The docstring of a class can be accessed by className.__doc__ as follows.

class MyNumber():
    """This is the docstring of this class.
    
    It describes what this class does and all its attributes."""
    def __init__(self, value):
        self.value=value
    def increment(self):
        """This is the docstring for this method.
        
        It describes what the method does, what are its calling conventions and
        what are its side effects"""
        self.value=self.value+1
        return self.value
print (MyNumber.__doc__)

Output:

This is the docstring of this class.
    
    It describes what this class does and all its attributes.

The docstring of a method can be accessed using className.methodName.__doc__ as follows.

class MyNumber():
    """This is the docstring of this class.
    
    It describes what this class does and all its attributes."""
    def __init__(self, value):
        self.value=value
    def increment(self):
        """This is the docstring for this method.
        
        It describes what the method does, what are its calling conventions and
        what are its side effects"""
        self.value=self.value+1
        return self.value
print (MyNumber.increment.__doc__)

Output:

This is the docstring for this method.
        
        It describes what the method does, what are its calling conventions and
        what are its side effects

The docstring of a function can be accessed using functionName.__doc__ as follows.

def decrement(number):
    """This is the docstring of this function.
    
    It describes what the function does, what are its calling conventions and
        what are its side effects"""
    number=number-1
    return number
print (decrement.__doc__)

Output:

This is the docstring of this function.
    
    It describes what the function does, what are its calling conventions and
        what are its side effects

Purpose of using a comment in python

Comments are used to increase the understandability of the code and they generally explain why a statement has been used in the program.

Purpose of using a docstring in python

A docstring begins with a capital letter and ends with a period and it describes metadata of the object with which it is associated including parameters, calling conventions, side effects etc. Docstrings are used to associate the documentation with the objects like classes, methods and functions in python and they describe what the object does.    

Conclusion

In this article, we have looked at the difference between comments and docstrings in python by looking at how they are declared in the source code and what are their uses. Stay tuned for more informative articles.