10. Docstrings and Documentation#
Observation 10.1 (Eagleson’s Law of Programming)
“Any code of your own that you haven’t looked at for six or more months might as well have been written by someone else.”[1]
Observation 10.2 (Guido van Rossum on clear code)
“Code is more often read than written.”[2]
Good documentation is critical to the ability of yourself and others to understand and disseminate your work and to allow others to reproduce it. As Eagleson’s Law of Programming implies in Observation 10.1 above, one of the biggest benefits of good documentation might be to the core maintainers and original code writers of a project. Despite the aspiration that the Python programming language be easy and intuitive enough to be its own documentation, we have often found than any not-well-documented code written by ourselves that is only a few months old is more likely to require a full rewrite rather than incremental additions and improvements.
Python scripts allow for two types of comments: inline comments (which are usually a line or two at a time) and docstrings, which are longer blocks set aside to document the source code. We further explore other more extensive types of documentation including README files, Jupyter notebooks, cloud notebooks, Jupyter Books, and published documentation forms.
A good resource is the RealPython tutorial entitled, “Documenting Python Code: A Complete Guide” [Mertz, 2023].
10.1. Inline comments#
“PEP 257–Docstring Conventions” differentiates between inline comments, which use the # symbol, and one-line docstrings, which use the """...""" format [Goodger and van Rossum, 2001]. An block of code with inline comments might look like:
# imports
import numpy as np
# create an array of zeros
zeros_array = np.zeros(10)
These types of comments are short and help to clarify what is to appear in the next few lines. They help to remind others (or the future you) why you did something. In this time of large language models, and GitHub Copilot they also provide valuable input for feed-forward models and make it much more likely the AI predicts your next line of code and writes it for you.
10.2. Docstrings#
Docstrings are longer blocks of comments that are set aside to document the source code. Docstrings are usually multi-line and are enclosed in triple quotes """...""". Docstrings are most often used at the top of a module to document what it does, and the functions it contains, and just after function or class definitions to document what they do. Docstrings can also be used to document variables and other objects. Docstrings can be accessed by the help() function and are used by the pydoc module to automatically generate documentation for your code.
The following is an example of a docstring for a function:
def FOC_savings(c, r, beta, sigma):
r"""
Computes Euler errors for the first order condition for savings from
the household's problem.
.. math::
c_{t}^{-\sigma} = \beta (1 + r_{t+1}) c_{t+1}^{-\sigma}
Args:
c (array_like): consumption in each period
r (array_like): the real interest rate in each period
beta (scalar): discount factor
sigma (scalar): coefficient of relative risk aversion
Returns:
euler (Numpy array): Euler error from FOC for savings
"""
if sigma == 1:
muc = 1 / c
else:
mu_c = c ** (-sigma)
euler_error = mu_c[:-1] - beta * (1 + r[1:]) * mu_c[1:]
return euler_error
A few notes on this documentation of the FOC_savings function. First, see that the docstring starts of with a clear description of what the function does. Second, you can see the :math tags that allow you to write LaTeX equations that will be rendered in the documentation. Docstrings written using reStructuredText markup can be compiled through various packages to render equations and other formatting options. Third, the Args and Returns sections are used to document the arguments and return values of the function.
“PEP 257–Docstring Conventions” give suggested format and usage for docstrings in Python [Goodger and van Rossum, 2001]. And there are two main styles for writing docstrings, the [Google style]*(https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and the NumPy style. While there are other ways to write docstrings (even those that meet PEP 257 standards), these two styles are so commonly used and are compatible with the Sphinx documentation package that we recommend using one of these two styles. OG-Core used the Google style, so you might adopt that to be consistent.
10.3. README file#
README files are a common way to document software. These are typically plain text files that include file structures and instructions on running the software.
If your project is hosted on GitHub, it would make sense to write the README file in Markdown. Markdown is a lightweight markup language that is easy to read and write and can be rendered in HTML, a very nice feature when you have this file on the internet via GitHub. Markdown is used in many places including GitHub, Jupyter notebooks, and Jupyter Book documentation. See the Markdown Guide for more information on Markdown. And you can see an example of a README file written with Markdown in the OG-Core repository here.
10.4. Jupyter notebooks#
As discussed in the Introduction to Python Chapter, Jupyter notebooks are a great way to interactively work with Python. They are also a great way to document your work. You can write Markdown in cells of these notebooks to provide text around your blocks of code. This Markdown can then be compiled to render nice formatting. You can also use the code cells to document your code just as you would in any Python script. You can see an example of a Jupyter notebook in the Cost-of-Capital-Calculator` repository here. As you can see in that example, Jupyter notebooks are rendered as HTML on GitHub, making viewing them easy.
10.5. Cloud notebooks#
Google Colab provides cloud-hosting for Jupyter notebooks. These have all the same functionality as locally hosted notebooks described above, but they are hosted on Google’s servers. This allows you to share your work with others and to collaborate on projects. It also means you can run Python (or other languages) without the need to install any special software on your machine. You just need a browser, internet connection, and Google account.
10.6. Jupyter Book documentation#
For long and detailed documentation, Jupyter Books are a great option. Jupyter Books are a collection Markdown, ReStructuredText, MyST files and Jupyter notebooks that are compiled into a book format. Jupyter Books can be compiled to HTML or PDF formats, making them easy to share. This training guide was created in Jupyter Book!
10.7. Other published documentaiton#
Put discusion of other forms of published documentation here such as white papers, peer-reviewed articles, websites (readthedocs by Sphinx).
10.8. Exercises#
Exercise 10.1
Take a function your wrote in your solution to Exercise 9.4. Add a docstring to this function that uses the Google style.
10.9. Footnotes#
The footnotes from this chapter.