Coding conventions

This page contains guidelines for coding conventions in python-control.

• We currently use PEP8 naming conventions as a baseline.
• We use numpydoc for docstrings, with the users manual generated by sphinx

You should also take a look at the testing conventions page.

Function naming conventions

• Function names are lower case, with underscores between words.

• Function that carry out an action on an object and return a new object (or set of values) are written in verb form. Examples: find_eqpt, solve_ocp.

• Functions that generate plots should end in _plot. Examples: bode_plot, nyquist_plot.

• For commands that map to MATLAB commands, it is not necessary to replicate the MATLAB command name if it violates the guidelines above. Instead, use the standard naming conventions and then create a second function object with the shortened name (eg, bode = bode_plot). You can also create an object in the matlab module that users the same name and signature as the MATLAB command.

Docstring conventions

We use numpydoc for docstrings, with the users manual generated by sphinx. In order for the readthedocs to render properly, the numpydoc conventions must be followed. Here's a short summary of the key conventions for standard functions:

1. Short summary: one line summary (shows up in tables).
2. Extended Summary: A few sentences giving an extended description.
3. Parameters: Description of the function arguments, keywords and their respective types. Format should be

   parameter : type
       Short description
   

   The type should either be a Python type, a NumPy class, or a python-control class, ideally with a :class: prefix to generate a link to the appropriate class.
4. Returns: Explanation of the returned values and their types.
5. Other Parameters: An optional section used to describe infrequently used parameters.
6. See Also: An optional section used to refer to related code.
7. Notes: An optional section that provides additional information about the code, possibly including a discussion of the algorithm. This section may include mathematical equations, written in LaTeX format.