Docstrings

In session 2 we discussed how to write readable code, and insodoing touched on the use of comments to explain a piece of code’s functionality.

We can extend this idea of readability to functions by using docstrings - a large block comment at the start of a function which describes what the function does, what its inputs are, and what its outputs are.

To use an example, consider the function below which calculates the kinetic energy of a particle as

\[ E_\mathrm{K} = \frac{1}{2} mv^2 \]

def kinetic_energy(m, v, verbose=False):
    ke = (1 / 2) * m * v ** 2
    if verbose:
        print(f'Kinetic energy = {ke:.2f} J')
    return ke

The purpose of this function might seem fairly obvious, but its good practice to write a docstring for all functions. We can add a docstring using triple quotes

def kinetic_energy(m, v, verbose=False):
    '''
    Calculate the kinetic energy as 1/2mv^2.

    Arguments
    ---------
    m: float
        The mass of the particle in kg
    v: float
        The velocity of the particle in m/s
    verbose: bool, default False
        If True, print the calculated kinetic energy.

    Returns
    -------
    float
        The kinetic energy of the particle in Joules.
    '''
    ke = (1 / 2) * m * v ** 2
    if verbose:
        print(f'Kinetic energy = {ke:.2f} J')
    return ke

We can split this into several sections.

1. A description of the function’s purpose - a general summary.

2. The input arguments - specifying their name, type, and meaning. We can also specify default values for optional arguments.

3. The return values - its type and meaning. Notice that as users we don’t care about the name of the return variable since the name is only important within the function’s local scope.

We’ve chosen a specific style for writing docstrings based on the Numpy style and you should keep to this style in this course.

We can access the docstring for a given function using the __doc__ attribute, e.g.

print(kinetic_energy.__doc__)

    Calculate the kinetic energy as 1/2mv^2.

    Arguments
    ---------
    m: float
        The mass of the particle in kg
    v: float
        The velocity of the particle in m/s
    verbose: bool, default False
        If True, print the calculated kinetic energy.

    Returns
    -------
    float
        The kinetic energy of the particle in Joules.

This is also possible for built-in functions like len

print(len.__doc__)

Return the number of items in a container.

Warning

You should write a docstring for every function, and your docstring should always match what the function actually does, requires as input, and gives as output.