Coding conventions

Style

PEP 8 rules

We aspire to the Zen of Python

docstrings

All public functions should have docstrings written using Restructured Text (reST), see the CheatSheet, and processed by Sphinx.

• We use the standard not Google or NumPy conventions.

• Each doctstring is layed out as:

"""
One line description, doesn't include name of function

parameter and return description using :param:, :type:, :return:, :type:

Optional intro para.

- ``use case 1`` descriptive text

- ``use case 2`` as above, then descriptive text

Ideally we have examples

Examples::
    >>> do this thing
    this is the result
    >>> do this other thing
    this is the other result

:notes:
 - note 1
 - note 2

:references:
 - ref1
 - ref2

:seealso:  :func:`~func or method`, :func:`~func or method`  etc
"""

• for a vector argument that is passed to spatialmath.base.argcheck.isvector the type is array-like as used in Numpy.
• In the "descriptive text", if you refer to variables in the use case put them in double backticks, ie. ``q``
• Code examples are good, use them if you can, they make the code more real.
• Use math notation :math:LaTeX math expression, no $ required, but make sure to change the docstring a raw string, ie. start it off with r"""

Unit testing

We use pytest

Code quality

We use codecov to analyse and display unit test coverage, we aim for over 90% coverage.

We use LGTM to analyse and display code quality, we aim for an A rating.

Coding patterns

We strive to be Pythonic rather than MATLABish.

• we prefer for x in X rather than for i in range() and indexing. If X is a NumPy array then x iterates over matrix rows. If we do need an index as well as the object, then use enumerate().
• we test arguments for appropriateness and raise a ValueError or TypeError
• for argument checking we use spatialmath.base.argcheck
  • we test for a scalar argument using isscalar
  • we test for a vector argument using isvector which accepts a Python list, tuple or NumPy array