(target-style-doc-guidelines)=
# Style and Documentation Guidelines

The purpose of this document is to establish Aeon's code style and documentation guidelines.

We generally adhere to [pep8](python-pep:0008), [pep257](python-pep:0257), and [google's style guide](https://google.github.io/styleguide/pyguide.html) for code and docstring style guidelines. 
We run ruff and pyright to format our Python code, the config settings for which can be found in a repository's `pyproject.toml`. 
We also believe in the [readme manifesto](https://www.thinkinghard.com/blog/TheREADMEManifesto), which says that `readme` files should provide at least a general description that covers _all_ of a project's files, and that one `readme` per subdirectory is generally good practice.

## General guidelines

* All files contain a header that briefly describes the contents within a few sentences.
* In general, more lines for the sake of clarity is preferred over brevity.

## Function and class docstrings

* Function names should describe the action they perform. Functions have the following sections in the given order:
  - One-line summary description, typically as a verb phrase
  - Long description (optional)
  - Inputs
  - Outputs
  - Examples (optional if included in a separate file)
  - Warnings/Exceptions (optional)
  - Additional notes (optional)
  - See also (optional)
  - Todos (optional)
* Class names should describe the entity they represent. Classes have the following sections in the given order:
  - One-line summary description, typically as a noun phrase
  - Properties / Attributes
  - Long description (optional)
  - Examples (optional if included in a separate file)
  - Warnings/Exceptions (optional)
  - Additional notes (optional)
  - See also (optional)
  - Todos (optional)

## Whitespace conventions

* A tab/indent is set at four spaces.
* Vertical whitespace is used sparingly, but can be used to improve readability between code blocks/sections.
* Horizontal whitespace is used sparingly, but can be used to improve readability between long and/or complex operations and conditionals.
* Each line contains no more than 108 characters.
* Line terminations are LF, not CRLF.

## Comment conventions

* Block comments are written as full sentences above the corresponding code. 
* Inline comments are written as a short phrase that starts two spaces after the corresponding code.
* Code referenced in comments are surrounded by back ticks for readability.
* Comments are used to describe variables where they are declared.

## Additional conventions

* Naming conventions:
  - Variable and function names are in lower snake_case (e.g. `exp_ref`, `infer_parameters` with a `_` in between each individual word representation).
  - Classes are in upper Snake_Case (e.g. `Alyx_Panel`).
  - Prefix 'n' is used for integer values e.g. `n_items`.
  - Suffix 'num' is used for referring to a particular instance e.g. `item_num`.
  - Suffixes that indicate unit measurement are used when using multiple units e.g. `wheel_deg` and `wheel_mm`.
  - Reuse of variable names (i.e. mutation) is generally avoided.
  - Variables across related files which share names should share meanings.
* Comments are for explaining _what_ a particular chunk of code does when it may be unintuitive, not for explaining exactly _how_ the code does what it does.
* Block comments read as a narrative.
* In function calls, keyword arguments should should be specified when not obvious.
* Leading underscores are reserved for "private" functions.