Code Style

We attempt to maintain a consistent coding style across projects so contributors do not have to keep dozens of different styles in their head as they move from project to project.

Python

We follow the PEP8 style guide for Python. Projects should make it easy to check new code for PEP8 violations preferably by Ruff. It is up to the individual project to choose an enforcement method, but it should be clearly documented and continuous integration tests should ensure code is correctly styled before merging pull requests.

There are a few PEP8 rules which will vary from project to project. For example, the maximum line length might vary. The test suite should enforce this.

Linting

Ruff is capable of running a lot of rules to lint the source code. The categories of rules to be run can be selecting by configuring ruff in the pyproject.toml file.

A reasonable set of rules and configuration can be found in the Cookiecutter template’s pyproject.toml file.

Auto formatting

The Black tool is an automatic code formatter for Python. From the website:

By using Black, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.

Your text editor is very likely to have a plugin to run Black on file saving. The documentation has instructions to set it up in Vim and in VS Code (and in Emacs).

Enforcement

Projects should automatically enforce code style. How a project does so is up to the maintainers, but several good options are documented here.

Tox

Tox is an excellent way to test style. For example, adding the following snippet to your tox.ini file will run ruff as part of your test suite:

[testenv:lint]
deps =
    ruff
commands =
    python -m ruff check {posargs:.}

[testenv:format]
deps =
    black
commands =
    python -m black --check {posargs:.}

Remember to add lint and format to your Tox envlist.

Pre-Commit

Pre-commit is a git hook that will run before Git stores a commit. It has the ability to run a set of tools against the files that are to be committed, and thus will let the developer know of errors and violations early in the development process. Install the pre-commit package and run pre-commit install to setup the hook.

The tools to be run are listed in a .pre-commit-config.yaml file at the top of the repository. You can find an example in our CookieCutter template’s .pre-commit-config.yaml file.

It is also possible and recommended to run the pre-commit checks as part of the test suite in tox, see for example the checks section in our CookieCutter template’s tox.ini file.

Javascript

Javascript files should be formatted using the prettier code formatter. It has support for many editors and can integrate with ESLint to check the code automatically.

Want to help? Learn how to contribute to Fedora Docs ›