3.4.4. Docstrings#
Although our solutions to the previous exercises do work, they could be much more documented. Keep in mind that code is wrote once, often by only one programmer, but it is read many times after, often by other people. An undocumented function is usually clear to the programmer while it is being written, but will it be months later?
Docstrings are the most important way to document functions. A docstring is a string that documents a function. While being optional, it is helpful in any code other than very simple scripts. A standard docstrings is a triple-quote string placed just below the function signature. Minimally, a docstring clearly indicates:
What the function does;
What are the types and contents of every expected parameter;
What are the type and contents of the return value, if any.
Here is what a good docstring looks like:
def format_info(i_participant, first_name, last_name, age, height, weight):
"""
Format the provided information into a human-readable string.
Parameters
----------
i_participant : int
Identifier for the participant
first_name : str
First name (given name) of the participant
last_name : str
Last name (surname) of the participant
age : float
Age of the participant, in years
height : float
Height of the participant, in meters
weight : float
Weight of the participant, in kg
Returns
-------
str
A human-readable string based on the provided information.
"""
output = (
"=============\n"
f"Participant {i_participant}: {first_name} {last_name}\n"
f"{age} years old\n"
f"Height: {height} m\n"
f"Weight: {weight} kg\n"
f"BMI: {weight / (height ** 2):.2f}\n"
"============="
)
return output
Note
The style used for this docstring is numpydoc. There is no requirement to follow this specific style over another one, but since it is used by most major Python packages in numerical analysis (NumPy, Pandas, Matplotlib, SciPy), then we also follows this style.
As you notice in the example above, there are more lines of documentation than lines of code. This is not unusual, and this is not a bad practice. After all, a well-documented, simple code is much better than an undocumented, complex code!
Since they are so ubiquitous, docstrings can be read without having to open the function’s source code. Try executing the last function definition, then:
Type
format_info
in Spyder’s help browser. The docstring appears, all well-formatted, as pictured in Fig. 3.4.
Or type
help(format_info)
in the console:
help(format_info)
Help on function format_info in module __main__:
format_info(i_participant, first_name, last_name, age, height, weight)
Format the provided information into a human-readable string.
Parameters
----------
i_participant : int
Identifier for the participant
first_name : str
First name (given name) of the participant
last_name : str
Last name (surname) of the participant
age : float
Age of the participant, in years
height : float
Height of the participant, in meters
weight : float
Weight of the participant, in kg
Returns
-------
str
A human-readable string based on the provided information.