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.
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"""
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
print(fib.__doc__) # Print Fibonacci series up to n
print(Article.__doc__) # Article class that holds information about an article of blog
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.
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.
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.
Happy Coding. Never Stop Hacking!!