From df0aeeeee0378f2d2cdc33cbb38e17c3b8b53bde Mon Sep 17 00:00:00 2001 From: =?utf8?q?Felix=20Hild=C3=A9n?= Date: Sat, 29 Jan 2022 02:49:43 +0200 Subject: [PATCH] Formalise style preference description (#2818) Closes #1256: I reworded our style docs to be more explicit about the style we're aiming for and how it is changed (or isn't). --- docs/the_black_code_style/current_style.md | 15 +++++++++------ docs/the_black_code_style/index.rst | 4 ++++ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md index 5be7ba6..0bf5894 100644 --- a/docs/the_black_code_style/current_style.md +++ b/docs/the_black_code_style/current_style.md @@ -2,10 +2,14 @@ ## Code style -_Black_ reformats entire files in place. Style configuration options are deliberately -limited and rarely added. It doesn't take previous formatting into account, except for -the magic trailing comma and preserving newlines. It doesn't reformat blocks that start -with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`. +_Black_ aims for consistency, generality, readability and reducing git diffs. Similar +language constructs are formatted with similar rules. Style configuration options are +deliberately limited and rarely added. Previous formatting is taken into account as +little as possible, with rare exceptions like the magic trailing comma. The coding style +used by _Black_ can be viewed as a strict subset of PEP 8. + +_Black_ reformats entire files in place. It doesn't reformat blocks that start with +`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`. `# fmt: on/off` have to be on the same level of indentation. It also recognizes [YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a courtesy for straddling code. @@ -18,8 +22,7 @@ running `black --preview`. _Black_ ignores previous formatting and applies uniform horizontal and vertical whitespace to your code. The rules for horizontal whitespace can be summarized as: do -whatever makes `pycodestyle` happy. The coding style used by _Black_ can be viewed as a -strict subset of PEP 8. +whatever makes `pycodestyle` happy. As for vertical whitespace, _Black_ tries to render one full expression or simple statement per line. If this fits the allotted line length, great. diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst index 3952a17..511a6ec 100644 --- a/docs/the_black_code_style/index.rst +++ b/docs/the_black_code_style/index.rst @@ -12,6 +12,10 @@ The Black Code Style While keeping the style unchanged throughout releases has always been a goal, the *Black* code style isn't set in stone. It evolves to accommodate for new features in the Python language and, occasionally, in response to user feedback. +Large-scale style preferences presented in :doc:`current_style` are very unlikely to +change, but minor style aspects and details might change according to the stability +policy presented below. Ongoing style considerations are tracked on GitHub with the +`design `_ issue label. Stability Policy ---------------- -- 2.39.5