9. Docstrings and Documentation

This chapter was coauthored by Jason DeBacker and Richard W. Evans.

Observation 9.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 9.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 9.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].

9.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-forwrd models and make it much more likely the AI predicts your next line of code and writes it for you.

9.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 containts 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.

9.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.

9.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.

9.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.

9.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!

[TODO: Show the slick rst interface between Sphinx and the OG-Core modules that automatically compile LaTeX documentation into the Jupyter Book API documentation. See this Jupyter Book API chapter on Firms and the code that created it in this folder.]

9.7. Other published documentaiton

Put discusion of other forms of published documentation here such as white papers, peer-reviewed articles, websites (readthedocs by Sphinx).

9.8. Exercises

Exercise 9.1

Take a function your wrote in your solution to Exercise 8.4. Add a docstring to this function that uses the Google style.

9.9. Footnotes

The footnotes from this chapter.

---

[1]

We could not find a proper citation for the source of this quote “Eagleson’s Law of Programming”. Some entries on this thread entitled “Who is Eagleson and where did Eagleson’s law originate?” suggest that the quote is at least as old as 1987 and is likely from Peter S. Eagleson, a member of the MIT faculty since 1952. However, neither the date, nor the author is confirmed.

[2]

This is a quote from Guido van Rossum, the original creator of the Python programming language, supposedly from an early PyCon conference. This quote is referenced in one of the early Python Enhancement Proposals, “PEP 8–Style Guide for Python Code” [van Rossum et al., 2001].