== 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 https://www.python.org/dev/peps/pep-0008/[PEP8] style
guide for Python. Projects should make it easy to check new code for
PEP8 violations preferably by
https://docs.astral.sh/ruff/[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.

[NOTE]
====
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
https://docs.astral.sh/ruff/configuration/[configuring ruff] in the
`pyproject.toml` file.

A reasonable set of rules and configuration can be found in the
Cookiecutter template's
https://github.com/fedora-infra/cookiecutter-python-app/blob/main/%7B%7B%20cookiecutter.slug%20%7D%7D/pyproject.toml#L77[pyproject.toml]
file.


==== Auto formatting

The https://black.readthedocs.io/[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

https://tox.wiki[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

https://pre-commit.com/[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
https://github.com/fedora-infra/cookiecutter-python-app/blob/main/%7B%7B%20cookiecutter.slug%20%7D%7D/.pre-commit-config.yaml[.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
https://github.com/fedora-infra/cookiecutter-python-app/blob/5ad9adb75600ac13fc65bb9fd847e5091a5d983b/%7B%7B%20cookiecutter.slug%20%7D%7D/tox.ini#L34[tox.ini]
file.


=== Javascript

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