Python Docstrings

Introduction

Guido van Rossum(creator of Python) said

"Code is read much more often than it is written."

It is reflected in the design of Python that how much emphasis does it give to docstring. There are several best practices for defining docstring and two ways to access it- help() and __doc__.

Documentation is used to describe the design and structure of the various component of the program. It should be descriptive enough so that users, fellow developers and the original developer can understand the code alike. Generally, we write the purpose of the code-what it does, and how it should be used.

You might not feel the need of documenting when it's just a small program but as the codebase grows larger even you won't understand what your code does.

Docstring

A docstring(Documentation Strings) is a string literal that occurs as the first statement in a module, function, class, or method definition. Docstring is recommended to be surrounded by """triple double quotes""".

Let's how to use docstring in function, class, and module.

Docstring in functions

def fib(n):
"""Print Fibonacci series up to n"""
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()

Docstring in Classes

class Article:
    """Article class that holds information about an article of blog"""
    def __init__(self, pub_date, title, content, reporter):
        """Creates an article object using pub_date, title, content, reporter"""
        self.pubished_date = pub_date
        self.title = title
        self.content = content
        self.reporter = reporter

    def get_title(self):
        """Return title of an article"""
        return self.title

    def get_content(content):
        return content

Docstring in Module

You can insert the above function and class in a file named test.py and at the beginning of the file add this docstring:

"""Example file containing a function - fib and a class - Article"""

Accessing docstring

Sometimes you may want to access the docstring, in this case, you can use __doc__ the attribute. This attribute is available for every function, class, and module. If it is not defined it returns None. You can how to use __doc__ for

Function

print(fib.__doc__)
# Print Fibonacci series up to n

Class

print(Article.__doc__)
# Article class that holds information about an article of blog

Module

import test
print(test.__doc__)
# Example file containing a function - fib and a class - Article 

When docstring is not defined it returns None.

print(Article.get_content.__doc__)
# None

Python docstring can be in a single line or can span over multiple lines.

One-line Docstrings

In the above all examples we saw one-line docstrings. Common practices for one-line docstrings-

  • There's no blank line either before or after the docstring.
  • The docstring is a phrase ending in a period.
  • The tone of docstring should be imperative or command. e.g Calculate square of a given number but not Calculates of a given number or Returns square of a number.

Multi-line Docstrings

If you've noticed any popular Python packages, they generally contain multi-line docstring. It is because they need to describe all the arguments, return type and sometimes exceptions raised too. Not only this, docstring when written in a specific format can be used to render the documentation in formats like HTML, printable PDF, or plain text; using documentation generator tools like sphinx.

Common practices for multi-line docstrings-

  • The summary line can be on the same line as the opening quotes or the next line.
  • The entire multi-line docstring is indented the same as the quotes at its first line.
  • The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).
  • The docstring for a module should generally list the classes, exceptions, and functions (and any other objects) that are exported by the module, with a one-line summary of each.
  • The docstring for a class should summarize its behavior and list the public methods and instance variables.

 

References:

PEP 257 -- Docstring Conventions

Happy Coding. Never Stop Hacking!!

0 Comments

Join discussion:

Login