In this section you will:
- Place some code in a module.
- Provide inline documentation (a “docstring”).
As a concrete example, let’s suppose we have a simple function that encodes Snell’s Law. Perhaps this function currently lives in a Jupyter notebook or a
.py file in an email attachment. We want to put into some more lasting, maintainable, reusable, and/or shareable form.
Here is the code:
# contents of refraction.py import numpy as np def snell(theta_inc: float, n1: float, n2: float) -> float: """ Compute the refraction angle using Snell's Law. See https://en.wikipedia.org/wiki/Snell%27s_law Parameters ---------- theta_inc : float Incident angle in radians. n1, n2 : float The refractive index of medium of origin and destination medium. Returns ------- theta : float refraction angle Examples -------- A ray enters an air--water boundary at pi/4 radians (45 degrees). Compute exit angle. >>> snell(np.pi/4, 1.00, 1.33) 0.5605584137424605 """ return np.arcsin(n1 / n2 * np.sin(theta_inc))
Notice that this example includes inline documentation — a “docstring”. This is extremely useful for collaborators, and the most common collaborator is Future You! It also includes type hints; this tells a programmer, type checker, or IDE what types are expected in an out of the function.
Further, by following the numpydoc standard, we will be able to automatically generate nice-looking HTML documentation later. Notable features:
At the top, there is a succinct, one-line summary of the function’s purpose. It must one line.
(Optional) There is an paragraph elaborating on that summary.
There is a section listing input parameters, with the structure
parameter_name : parameter_type optional description
Note that space before the
:. That is part of the standard.
Similar parameters may be combined into one entry for brevity’s sake, as we have done for
There is a section describing what the function returns.
(Optional) There is a section of one or more examples.
We will revisit docstrings in the section on writing documentation [TODO: link once this section exists].