diff --git a/doc/guide/developing.rst b/doc/guide/developing.rst index 586710c11d3bac6bfe662846bf1856fbca8c90a2..63b9e32ca881258b7b72da78e1d0b141139eaa6d 100644 --- a/doc/guide/developing.rst +++ b/doc/guide/developing.rst @@ -22,8 +22,31 @@ Alternatively, especially for small changes, a development environment can be bu git lb-use DaVinci -Coding conventions ------------------- +Coding conventions, style and type hints +---------------------------------------- + +Python code in the stack follows the `PEP8 guidelines <https://peps.python.org/pep-0008/>`_ +and other general good practices: + +* Include comments and documentation ("docstrings") when the intent of a line, function, class, or module is not obvious. +* Factor code into functions when there is repetition and/or for clarity. +* When modifying an existing file, following the conventions of the surrounding code. + +Style and formatting checks are implemented in continuous integration (see subsection below) +via `pre-commit <https://pre-commit.com/>`_ hooks. +The following hooks are implemented: `Black`, `codespell`, `Flake8`, `pre-commit-hooks`, `pyupgrade`. +Refer to the repository `.pre-commit-config.yaml` for the actual implementation details. + +Developers are encouraged to run the hooks locally prior to pushing to the repositories. +This is easily done with the following: + +.. code-block:: bash + + pre-commit install # only needed once to install pre-commit + pre-commit run --all-files # example to run all hooks on all files + +Static typing (hints) is available in Python 3 and the offline stack now implements type hints and checking thereof. +Type hints are for now not compulsory but are strongly encouraged. Tests and continuous integration