Python Docstrings: What Are Docstrings in Python? Docstrings vs. Comments?

Python Docstrings

Python Docstrings or Python documentation string: Python docstrings is used to associate documentation with Python modules, functions, classes, and methods. In simple words, “A docstring is a string that is inserted at the beginning of a module, function, class, or method in Python.

It is used to describe what the function does. Docstrings look like a comment, but it is not the same as a comment.

Docstrings has a fixed place, and we should write docstrings at that place. If we write docstrings anywhere in our code, then it is useless. Always remember, “The docstring for a Python code object (module, class, function, etc.) is the first statement of that code object, immediately following the definition.” It means docstrings should be the first statement after we created a function or a class.

How to Create Docstrings in Python?

Docstrings are created by using triple double-quotes. Triple double-quotes are used to create multiline strings, but unless we assign that string to any variable, it works as docstrings. So normally, if we create a string with triple double-quotes without assigning it to any variable, that is a docstring if we place it in the right place. For example:

Code:
def first_function():
    """This is the correct place
    to write docstrings"""
    print('learning docstrings')

Now here we created a function named first_function And, as we learned in the docstring definition. Docstring should be the first statement of the object. So here our object is a function, so as soon as we created the function. The next statement is docstrings. This is the right place for writing docstring.

Here we used triple double-quotes to write docstrings. If we want, we can use triple single-quotes and still it will work as docstrings. But according to Docstring Conventions, it’s recommended to use triple double-quotes to write docstrings. So we can say it is a convention to write triple double-quotes for docstrings.

How to Access Docstrings in Python?

We can access docstrings in output. For example:

Code:
def first_function():
    """This is the correct place
    to write docstrings"""
    print('learning docstrings')
first_function()

Output:
learning docstring

In a normal way, when we call the function. We didn’t get the docstring part in the output. It was just like comments; we didn’t get comments in output. They were just ignored by the interpreter. So that’s why we can use docstrings as comments when we want to write multiline comments. But comments cannot be accessed in output, but docstrings can.

We used the built-in function __doc__ to access docstrings in output.

Code:
def first_function():
    """This is the correct place
    to write docstrings"""
    print('learning docstrings')
print(first_function.__doc__)

Output:
This is the correct place
to write docstrings

Now we get the docstrings in output. So this is how we can access docstrings. We used function name with __doc__ because we are accessing the function docstrings.

Now what if we write docstrings in another place? See if we can get it in output. For example:

Code:
def first_function():
    print('learning docstrings')
    """This is the correct place
    to write docstrings"""
print(first_function.__doc__)

Output:
None

We get None in the result. However, we wrote the docstrings in function but did not place them in the correct place. Docstring should be the first statement after function, but we write print as the first statement, and after that we write docstrings. So that’s why we get None in the result.

Now what if we used single triple-quotes or may be normal double quotes for writing docstrings? For example:

Code:
def first_function():
    '''This is the docstrings with single triple-quotes'''
    print('learning docstrings')
print(first_function.__doc__)

Output:
This is the docstrings with single triple-quotes

Another example:

Code:
def first_function():
    "this is the docstrings with double quotes"
    print('learning docstrings')
print(first_function.__doc__)

Output:
this is the docstrings with double quotes

In both upper examples, we get docstrings in output, but it is not recommended to use any other type of quotes instead of triple double-quotes for docstrings. PEP (Python Enhancement Proposal) recommended we should use triple double-quotes.

Now in the upper example, we write docstring for function. What if we write docstrings outside the function? For example:

Code:
"""In the following code,
we are creating two function."""
def first_function():
    print('First function')
def second_function():
    print('Second function')
print(__doc__)

Output:
In the following code,
we are creating two function.

Now we write docstrings at the beginning of our program. And this docstring is related to this whole program. This is not related to any function. That’s why, when we use, print(__doc__) we didn’t use any function name with __doc__ because we are not accessing any function’s docstrings. It is possible that function has separated docstrings. For example:

Code:
"""In the following code,
we are creating two function."""
def first_function():
    """This is separated doc string for function"""
    print('First function')
def second_function():
    print('Second function')
print(__doc__)
print(first_function.__doc__)
print(second_function.__doc__)

Output:
In the following code,
we are creating two function.
This is separated doc string for function
None

So when we used,print(__doc__) we wanted to access the whole program’s docstrings. When we used, print(first_function.__doc__) we wanted to access the docstring for first_function. When we used print(second_function.__doc__) we wanted to access the docstring for second_function and because we don’t have any docstrings for second_function we got None in the result.

Now back to the docstring outside the function. Just like we learned in function that docstring has a fixed place. Same goes with outside the function. If we want to write a docstring for the whole program, then it should be the first statement of the program. For example:

Code:
num1 = 100
num2 = 100
print(num1 + num2)
"""This is the docstrings: we are 
using print statement."""
print(__doc__)

Output:
200
None

We get None for docstrings because we didn’t put the docstrings in the right place. It should be the first statement:

Code:
"""This is the docstrings: we are
using print statement."""
num1 = 100
num2 = 100
print(num1 + num2)
print(__doc__)

Output:
200
This is the docstrings: we are
using print statement.

Now we get docstrings in output. So always remember to write the docstrings at their correct place.

One last example: in which we are creating and accessing docstrings for different objects.

Code:
"""This is the docstrings for this whole code."""
num1 = 100
num2 = 100
def first_function():
    """This is the docstrings for function."""
    print('Learning docstrings with function')
class FirstClass:
    """This is the docstrings for class."""
    name = "Python"
print(__doc__)
print(first_function.__doc__)
print(FirstClass.__doc__)

Output:
This is the docstrings for this whole code.
This is the docstrings for function.
This is the docstrings for class.

Use of help() to Access Docstrings in Python

Now in the upper example, we used __doc__ to access the docstrings. Their is another way to access the docstrings using help() function. For example:

Code:
def first_function():
    """This is the correct place
    to write docstrings"""
    print('learning docstrings')
help(first_function)

Output:
first_function()
    This is the correct place
    to write docstrings

So this is how we can use help() function to access the docstrings.

Types of Docstrings

There are different kinds of docstrings:

Single-line Docstrings

Multiline Docstrings

Google Style Docstrings

Numpydoc Style Docstrings

Single-line Docstrings

Single-line docstrings are used for short and simple documentation. Single-line docstrings should fit in one line within triple quotes and end with a period. It is also called one-line docstrings. For example:

Code:
def first_function(a,b):
    """Return the sum of two numbers."""
    return a + b

So this is how we write one-line docstrings.

Multiline Docstrings

Multiline docstrings are used for more detailed documentation. The first line of multiline docstrings is worked as a summary line; after that, we provide a blank line, and then we write docstrings. For example:

Code:
def add(a,b):
    """
    This function take two numbers as argument
    
    a = The first number
    b = The second number
    return the sum of two numbers
    """
    return a + b

So this is how we write multiline docstrings.

Google Style Docstrings

Google style docstrings follow a specific format and are inspired by Google’s documentation style guide. It provides a structured way to document Python code using indentation and headings.

Google-style docstrings follow a specific format, opening with a one-line summary of the function, method, or module, followed by a more detailed description.

Numpydoc Style Docstrings

Numpydoc-style docstrings are widely used in the scientific and data analysis community, particularly for documenting functions and classes related to numerical computations and data manipulation.

In Numpydoc style docstrings, docstrings begin with a one-line summary, then provide a function purpose, and after that, they include sections for parameters, returns, and exception handling.

Difference Between Docstrings and Comments

Docstrings and comments are different in Python. Consider the following topics to understand the difference between docstrings and comments.

Definition: Docstrings are multiline strings that are inserted at the start of an object, and it is the documentation of the object about what the object does. While comments are short, one-line or inline, provide the clarification of the code and how this code works. So remember, docstrings used to describe what this code does? and comments used to describe how this code works?

Create: We created docstrings by using triple double-quotes, while we created comments using the hash (#) sign.

Place: Docstrings have a fixed place in code; we can’t put anywhere docstrings in our code. While comments have no certain place. We can place comments anywhere in our program.

Access: We can access docstrings by using __doc__ functions or help(). But comments are not accessible. They are not visible in output.

Multiline: We can write multiline docstrings. But there is no direct way or official syntax for writing multiline comments in Python.

So these are some differences between Docstrings and Comments.

Conclusion

This is the end of the Python Docstrings tutorial. Docstrings is important but necessary. If you want to do proper documentation of your code, you used docstrings. Remember to write docstrings at their proper place. Also remember the difference between docstrings and comments.

End of Python Docstrings Tutorial

Click For Python Quotes Tutorial