In this tutorial we will discuss how to create docstrings for a Function in Python.
Having to create separate documentation for your Code can often be quite time-consuming and bothersome. Programmers often resort to using comments to document their code within the program itself to make life easier. However, there is a better way of documenting code easily through the use of Python docstrings.
How to create docstrings for Python Functions
A Docstring is a “string” that “documents” your code. That’s where the name “Docstring” came into being.
This string is placed on the first line after the function name, and is automatically detected by Python as a docstring. You can also verify this by accessing a docstring for a function using the __doc__ attribute.
We always write docstrings with multiline strings because they almost always need to be broken across several lines due to their length.
Functions Docstrings – Examples
So let’s take a look at some examples.
Let’s start off with a simple example, using a function which adds two number together.
def add(num1, num2):
return num1 + num2
Now let’s give it a doc-string.
def add(num1, num2):
"""Calculates the Sum of two Numbers"""
return num1 + num2
This docstring clearly states the purpose of the function, but is still lacking some important details.
Let’s try again.
def add(num1, num2):
"""
Calculates the Sum of two Numbers
Arguments:
num1 (int, float): The first number
num2 (int, float): The second number
Returns:
int, float : Sum of num1 and num2
"""
return num1 + num2
This style of writing docstrings is known as Google Docstrings. You can clearly see the arguments described here along with the possible types they might have. The return value and type are also mentioned.
However! Please note that sometimes adding comments or docstrings to functions can be rather redundant. If it’s a simple function, you can choose to only write a one-liner description, instead of the full docstring shown earlier.
Docstrings are meant to make code easier to understand. If you don’t use them correctly and use them more often than required, it will have the opposite effect.
Examples in this tutorial are purely for demonstrative purposes, not real-life examples.
Example# 2
Here we have a function that divides two numbers.
def div(num1, num2):
return num1 / num2
In such scenarios, we can run into an exception (Zero Division Error). When we know a possible exception can happen, we include it in the docstring.
def div(num1, num2):
"""
Calculates the Quotient of two Numbers
Arguments:
num1 (int, float): The first number
num2 (int, float): The second number
Returns:
int, float : Quotient of num1 and num2
Raises:
ZeroDivisionError: if num2 is zero
"""
return num1 / num2
Example# 3
Here is our last example.
The following code takes two parameters as a start and end point, and returns the sum of numbers between those points. There is a third optional parameter which can adjust the interval. For example, interval = 2 would sum every other number.
def rangeSum(start, stop, interval = 1):
sum = 0
for i in range(start, stop, interval):
sum += 1
return sum
Optional parameters like these, (those that have default values) should be declared as “optional” in the docstring.
def rangeSum(start, stop, interval = 1):
"""
Calculates sum of numbers from a start point
to an end point (start point is inclusive)
Arguments:
start (int): The starting value
stop (int): The end point
interval (int, optional): Interval between numbers
Returns:
int: Sum of numbers
"""
sum = 0
for i in range(start, stop, interval):
sum += 1
return sum
More about Python Docstrings
If you are interested in learning more about docstrings and their various applications, give the below articles a read!
This marks the end of the Python Function Docstrings Tutorial. Any suggestions or contributions for CodersLegacy are more than welcome. Questions regarding the tutorial content can be asked in the comments section below.