# 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