Python Docstrings - Simply Explained!

Coding is a language that is a tad bit alienated compared to all the languages that humans use to communicate with each other. Though the codes are run by machines, their development and maintenance usually fall within the hands of a human. Though AI might peek in, human touch is inevitable in coding at least for the near future. So, it is imperative that any program contains a textual explanation of what a specific set of codes aims to accomplish.

Python has an exclusive feature to serve that very purpose. Enter the Docstrings! Let us explore in detail about the docstrings in Python in the following sections.

What Are Docstrings and Where Do They Appear?

Rather than typing essays that tell how a particular part of the programming works, one can use docstrings to specify how a particular function or module or class or method is associated with the Python Program. This is done by recording what basic need a particular programming entity accounts for in the program.

Also known as the string literals, docstrings appear immediately after the line where a class or module or method or function is defined.

Best Practices for Creating Docstrings

The potential of a feature is fully utilized only when there are guidelines to govern its usage. Thus, the creation of docstrings is governed by a set of rules and guidelines so as to ensure its optimal usage in any program. Listed below is a concise description of each of those rules.

Every docstring should always begin with a UPPERCASE letter and end with a period ‘.’
When multiple lines are used the summary ought to be isolated from the rest of the explanation.
The first line of the docstring should be crisp, short & hit the bullseye rather than beating around the bush.
The contents of the docstring should be limited to the modules or classes or methods or functions that it augments.
There shall not be any blank line either preceding or succeeding a single line docstring.

Docstrings vs Comments

With all the explanation thus far, one might get a bit confused on the purpose of the docstring & begin to wonder, are these the same as the comments? It is natural to get such thoughts but there is a fine line that separates docstrings from comments. Let us have a look at it in detail.

Comments tell us about the functionality of a program whereas a docstring describes a specific part within that program.
While comments are invisible to a Python interpreter, the docstrings can be saved & read later through _doc_ or help( ) functions.
Comments are preceded by a hash symbol (#) whereas docstrings are preceded by triple double quotes (“”” “””) or triple single quotes (”’ ”’).

Declaring Docstrings in Python

Given below is an example demonstrating the declaration of docstrings in a user-defined function.

# print the square root of a number
def sqrt(x):
    """
    Takes the input 'x' and returns its square root.
 
    Arguments
    --------------
    x = int
    """
    print(x**0.5)

Output:

Docstrings describing a user-defined square root function

The above example clearly displays the difference between the usage of a comment & a docstring for a user-defined function. The former tells us about the result whereas the latter describes the process. It could also be seen that there are blank lines included when similar sections within the docstrings are to be grouped, for instance, the Arguments in the above example has a blank line above & below it to isolate it from the rest of the docstrings.

Conclusion

Now that we have reached the end of this article, hope it has elaborated on how to create docstrings for effective utilisation and the best practices associated with it in Python. Here’s another article that can be your definitive guide to the comments in Python. There are numerous other enjoyable and equally informative articles in CodeforGeek that might be of great help for you to gain valuable insights. Until then, ciao!