---
jupytext:
  formats: ipynb,md:myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.13.6
kernelspec:
  display_name: Python 3 (phys-581)
  language: python
  name: phys-581
---

```{code-cell}
:tags: [hide-cell]

import mmf_setup;mmf_setup.nbinit()
import logging;logging.getLogger('matplotlib').setLevel(logging.CRITICAL)
%matplotlib inline
import numpy as np, matplotlib.pyplot as plt
```

(sec:CodingStyle)=
Coding Style
============

It is useful to articulate a set of coding conventions for your project to maintain
consistency and to help your developers quickly understand code.  Although trivial from
the computer's perspective, this has several advantages for the users and developers:

1. Coding Efficiency: Developers need not waste time deciding what style to use.
2. Documentation: Following certain conventions can allow documentation tools to extract
   and display information clearly.

## Python

:::{margin}
The [PEPs][] are the Python Enhancement Proposals.  These are a set of documents
describing the development and evolution of the language.  If you want suggest a change
to the language, the process is to formulate this as a PEP, then lobby for its
acceptance. It is especially worth reading [PEP 20 -- The Zen of Python][PEP-20].
:::
```{code-cell}
:tags: [margin]
import this
```

Python has its own style guide described in [PEP-8][], most of which is enforced by
[Black][] -- "The uncompromising code formatter".  I recommend having your editor run
`black` whenever you save your code.  This removes most discussion about where spaces
should appear, formatting loops, lists etc.

## Docstrings

We use [Napoleon][] to extract our docstrings, so please follow the [NumPy Style
guide][], falling back to the syntax used by [Napoleon][] when ambiguous.  This aids in
generating our {doc}`_generated/api/index`.

[NumPy Style Guide]: <https://numpydoc.readthedocs.io/en/latest/format.html>
[Black]: <https://black.readthedocs.io/en/stable/>
[Napoleon]: <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/>
[PEPs]: <https://peps.python.org/pep-0000/>
[PEP-8]: <https://peps.python.org/pep-0008/>
[PEP-20]: <https://peps.python.org/pep-0020/>