synapse/docs/code_style.rst

# Code Style

The Synapse codebase uses a number of code formatting tools in order to quickly and automatically check for formatting (and sometimes logical) errors in code.

The necessary tools are detailed below.

## Formatting tools

The Synapse codebase uses [black](https://pypi.org/project/black/) as an opinionated code formatter, ensuring all comitted code is properly formatted.

First install black with:

pip install --upgrade black

Have black auto-format your code (it shouldn't change any functionality) with:

black . --exclude="\.tox|build|env"

• flake8

  flake8 is a code checking tool. We require code to pass flake8 before being merged into the codebase.

  Install flake8 with:

  pip install --upgrade flake8

  Check all application and test code with:

  flake8 synapse tests

• isort

  isort ensures imports are nicely formatted, and can suggest and auto-fix issues such as double-importing.

  Install isort with:

  pip install --upgrade isort

  Auto-fix imports with:

  isort -rc synapse tests

  -rc means to recursively search the given directories.

It's worth noting that modern IDEs and text editors can run these tools automatically on save. It may be worth looking into whether this functionality is supported in your editor for a more convenient development workflow. It is not, however, recommended to run flake8 on save as it takes a while and is very resource intensive.

## General rules

• Naming:
  • Use camel case for class and type names
  • Use underscores for functions and variables.
• Use double quotes "foo" rather than single quotes 'foo'.
• Comments: should follow the google code style. This is so that we can generate documentation with sphinx. See the examples in the sphinx documentation.
• Imports:

  • Prefer to import classes and functions rather than packages or modules.

    Example:

    from synapse.types import UserID
    ...
    user_id = UserID(local, server)

    is preferred over:

    from synapse import types
    ...
    user_id = types.UserID(local, server)

    (or any other variant).

    This goes against the advice in the Google style guide, but it means that errors in the name are caught early (at import time).

  • Multiple imports from the same package can be combined onto one line:

    from synapse.types import GroupID, RoomID, UserID

    An effort should be made to keep the individual imports in alphabetical order.

    If the list becomes long, wrap it with parentheses and split it over multiple lines.

  • As per PEP-8, imports should be grouped in the following order, with a blank line between each group:

    1. standard library imports
    2. related third party imports
    3. local application/library specific imports

  • Imports within each group should be sorted alphabetically by module name.

  • Avoid wildcard imports (from synapse.types import *) and relative imports (from .types import UserID).