Python Standards and Best Practice

The DevOps division are heavy users of the Python programming language for backend work.

Code style

Code style recommendations can be categorised as "structural" or "semantic". Structural recommendations cover how code should be structured. For example recommendations around whether to use tabs or spaces for indention, whether to leave one or two blank lines between functions and maximum line length are structural recommendations. Semantic recommendations cover what the code does. For example recommendations around maximum code complexity, asserting on complete object values rather than fields in tests or when to use object orientation are semantic recommendations.

For structural code style enforcement we recommend using the common CI pipeline which configures automated code style checks using flake8 and black. We also recommend adding pre-commit checks locally which will be enforced in CI via a pre-commit job.

A step-by-step explanation of how to configure the checks added by our standard templates can be found in the the Python package tutorial. A deeper explanation of other concepts like Tests, Logging, Packaging, etc, can also be found on the same page.

We do not have a separate semantic code style document at the moment. As a general recommendation, we suggest using Google's style guide as a base for teams to work from. The Google style guide explains the pros and cons of each recommendation so that teams may decide in an informed manner whether to deviate or not.