Style Guide#

This project is based on the python-copier-template, which integrates a number of tools which assist in usability and enforce style decisions. It is recommended that developers use a vscode devcontainer to easily take advantage of the tools available to them. You will need follow a short set of instructions to enable use of vscode devcontainers.

For this project, we follow the Google Python Style Guide with a notable set of exceptions.

dodal Specific Guidance#

Specific guidelines for use within this project which are not outlined in the Google Python Style Guide or PEP 8.

  1. Handle shared devices as outlined in handle devices shared between multiple endstations

Guidance Against the Google Python Style Guide#

Specific guidelines for use within this project which directly oppose decisions in the Google Python Style Guide.

  1. PEP 8 should take precedence over the google style guide on any naming disputes to ensure continuity throughout the project.

  2. If a ruff rule enforced by the python-copier-template contradicts the Google Python Style Guide, the ruff rule takes precedence. If you disagree with the applied ruff rule, please open an issue on the python-copier-template.

  3. Use absolute import statements for types, classes, or functions, rather than for packages and modules only. We should follow the PEP 8 guideline here rather than the decision in the google style guide, as ‘absolute imports are recommended, as they are usually more readable and tend to be better behaved’.

  4. Prefer making github issues over TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect. An issue allows for context and follow-up comments.

  5. Prefer using explicit true/false evaluation over implicit false evaluations. Explicit false evaluation is more predictable when handling different data types (i.e. integers), as 0 is falsy.

  6. Prefer Args: documented in the class docstring over __init__ docstring, to increase readability of auto-generated documentation.

Guidance Which Agrees with the Google Python Style Guide#

Specific guidelines for use within this project which agree with decisions in the Google Python Style Guide, but may be uncommon practice for those unfamiliar with Python. These tend to be guidelines which cannot be enforced by enabling a ruff rule.

  1. Use decorators judiciously when there is a clear advantage. Avoid staticmethod and limit use of classmethod.

  2. Use of properties over getters and setters is encouraged, unless getting or setting the variable is complex or the cost is significant, either currently or in a reasonable future.

  3. Avoid global mutable state where possible.

  4. Prefer the use of Args over Parameters when writing docstrings. An example is given in standards.