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).
This commit is contained in:
parent
4ce049dbfa
commit
df0aeeeee0
@ -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.
|
||||
|
@ -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 <https://github.com/psf/black/labels/T%3A%20design>`_ issue label.
|
||||
|
||||
Stability Policy
|
||||
----------------
|
||||
|
Loading…
Reference in New Issue
Block a user