1CODE STYLE
2==========
3
4The Python code style used in this project follows the [Black code style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html).
5
6# Formatting
7
8For now, we are configuring the `black` formatter with the option to leave quotes unchanged.
9The preferred quote style is single quotes, which isn't a configurable option for `Black`, so we are not enforcing it. This may change in the future.
10
11## Ignoring Commit for Git Blame
12
13The adoption of `Black` as a formatter came in late in the project, with already a large code base. As a result, a large number of files were changed in a single commit, which gets in the way of tracing authorship with `git blame`. The file `git-blame-ignore-revs` contains the commit hash of when that mass-formatting event occurred, which you can use to skip it in a `git blame` analysis:
14
15!!! example "Ignoring a commit with `git blame`"
16    ```
17    $ git blame --ignore-revs-file .git-blame-ignore-revs
18    ```
19
20# Linting
21
22The project includes a `pylint` configuration (see the `pyproject.toml` file for details).
23The `pre-commit` checks only enforce that there are no errors. But we strongly recommend that you run the linter with warnings enabled at least, and possibly the "Refactor" ('R') and "Convention" ('C') categories as well.
24To run the linter, use the `project.lint` invoke command.
25
26!!! example "Running the linter with default options"
27    With the default settings, Errors and Warnings are enabled, but Refactor and Convention categories are not.
28    ```
29    $ invoke project.lint
30    ```
31
32!!! example "Running the linter with all categories"
33    ```
34    $ invoke project.lint --disable=""
35    ```
36
37# Editor/IDE Integration
38
39## Visual Studio Code
40
41The project includes a `.vscode/settings.json` file that specifies the `black` formatter and enables an editor ruler at 88 columns.
42You may want to configure your own environment to "format on save" with `black` if you find that useful. We are not making that choice at the workspace level.
43
44