Commenting and docstrings

Commenting your code should come in two flavors.

First are inline comments which explain what the code is doing, for example

# Size (in units of pt) of arrow heads for plots of normal-mode current distributions
a_head = 3 

the more of these, the better!

The second, and most important comments are docstrings. These should describe at least what every function or class does, what parameters it accepts and what it returns, and ideally feature examples of typical use or some theoretical background.

This accomplishes two things:

• The docstring can automatically be transformed to content for the QuCAT website

• It will appear to a user who requests help on a function (for example by using shift-tab in a jupyter notebook)

Docstrings should be formatted as numpy style docstrings. As an example, this docstring

def zpf(self, mode, quantity, **kwargs):
    r'''Returns contribution of a mode to the zero-point fluctuations of a quantity for this component.

    The quantity can be current (in units of Ampere), 
    voltage (in Volts), 
    charge (in electron charge), 
    or flux (in units of the reduced flux quantum, :math:`\hbar/2e`).

    Parameters
    ----------
    mode:           integer
                    Determine what mode to consider, where 0 designates
                    the lowest frequency mode, and the others
                    are arranged in order of increasing frequency
    quantity:       string
                    One of 'current', 'flux', 'charge', 'voltage'
    kwargs:     
                Values for un-specified circuit components, 
                ex: ``L=1e-9``.

    Returns
    -------
    float
        contribution of the ``mode`` to the zero-point fluctuations of the ``quantity``

    Notes
    -----
    This quantity is calculated by multiplying the
    voltage transfer function :math:`T_{rc}` (between a reference component :math:`r`
    and the annotated component  :math:`c` ), with
    :math:`X_{zpf,m,r}`, the zero-point fluctuations of :math:`\hat{X}` at the reference component.
    
    Note that resistors make the transfer function :math:`T_{rc}`, and hence this quantity, complex.

    For more detail on the underlying theory, see https://arxiv.org/pdf/1908.10342.pdf.
    ''''''

Translates to the following website content