This tutorial will explain what docstrings are in the Python programming language and how they can be used.
What is a Docstring in Python?
A docstring is a string literal that is used to document your code.
A string literal is a sequence of characters 0 or more characters in length, which is to be treated as a single entity – i.e., it’s a string variable of any length.
A docstring appears after the definition of a module, class, method, or function and should explain the purpose of the object it appears under.
These docstrings can then be accessed to find out about the module, class, method, or function you are using.
Defining a Docstring – Triple Quotes!
A docstring is defined a bit differently from regular strings. For example, it’s not assigned to a variable name, and it’s triple quoted instead of single-quoted.
Here’s a single line docstring:
""" This is a single line docstring """
Here’s a multi-line docstring:
""" This is the first line of a multi-line docstring This is the second line of a multi-line docstring """
Using Docstrings for Code Documentation
The primary purpose of a docstring is to document your code (hence the name).
Here’s the best practice for documenting various objects in Python.
Documenting Functions & Methods
When creating a docstring to document a function or method, the docstring should be placed immediately after the function declaration, inside the function code block.
It’s best practice to document the purpose of a function, the parameters the function accepts, and the value it is expected to return.
def multiplyNumbers(num1, num2):
"""
Multiplies two given numbers passed as parameters
Parameters:
num1 (integer)
num2 (integer)
Returns:
The product of num1 and num2
"""
return num1 * num2
Documenting Classes
When creating a docstring to document a class, the docstring should be placed immediately after the line declaring the class inside the class code block.
Additional docstrings can be placed inside the class to document class methods.
Class FoodItem
"""
A class representing a food item
Attributes:
name - The name of the food
colour - The colour of the food
category - The category of the food
Methods:
getFoodDetails() - returns all of the attributes in a single string
randomFoodColour() - changes the colour of the food to one at random
"""
def __init__(name, colour, category):
"""
Class constructor
Defines and sets the attributes for the FoodItem Class
Parameters:
name (string)
colour (string)
category (string)
"""
self.name = name
self.colour = colour
self.category = category
# Code continues to define functions, etc
Documenting Modules
When documenting a module, you should document everything the module exports – so that when you access the docstring after importing the module, it can remind you what the module provides.
When documenting a module, the docstring should simply go at the top of the main Python file for the module.
The below docstring example is for a module FoodModule which performs some food-related tasks:
""" FoodModule Provides food related classes and functions Classes: FoodItem - a food item which contains name, colour and category fields FoodContainer - a container which can hold a food item, with foodItem and containerShape fields Functions: ContainFood - adds a given food item to a given container UncontainFood - removes a given food item from a given container """ # Code continues here
Accessing Docstrings with the doc Attribute
You can access the docstring for a module, function, method, or class by viewing its doc attribute:
print(multiplyNumbers.__doc__)
Accessing Docstrings with the help() Function
The help() function is built-in to Python and will display the docstring for a given object – this will not just print the docstring, but it will display the documentation for the function in an interactive shell similar to using the man command in the Linux shell:
help(multiplyNumbers)
Note that calling the help() function will halt the execution of your Python code until the q key is pressed to exit viewing the documentation/docstring.
