-You might have noticed that closing brackets are always dedented and
-that a trailing comma is always added. Such formatting produces smaller
-diffs; when you add or remove an element, it's always just one line.
-Also, having the closing bracket dedented provides a clear delimiter
-between two distinct sections of the code that otherwise share the same
-indentation level (like the arguments list and the docstring in the
-example above).
-
-Unnecessary trailing commas are removed if an expression fits in one
-line. This makes it 1% more likely that your line won't exceed the
-allotted line length limit.
-
-*Black* avoids spurious vertical whitespace. This is in the spirit of
-PEP 8 which says that in-function vertical whitespace should only be
-used sparingly. One exception is control flow statements: *Black* will
-always emit an extra empty line after ``return``, ``raise``, ``break``,
-``continue``, and ``yield``. This is to make changes in control flow
-more prominent to readers of your code.
-
-That's it. The rest of the whitespace formatting rules follow PEP 8 and
-are designed to keep `pycodestyle` quiet.
-
-
-### Line length
-
-You probably noticed the peculiar default line length. *Black* defaults
-to 88 characters per line, which happens to be 10% over 80. This number
-was found to produce significantly shorter files than sticking with 80
-(the most popular), or even 79 (used by the standard library). In
-general, [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260).
-
-If you're paid by the line of code you write, you can pass
-`--line-length` with a lower number. *Black* will try to respect that.
-However, sometimes it won't be able to without breaking other rules. In
-those rare cases, auto-formatted code will exceed your allotted limit.
-
-You can also increase it, but remember that people with sight disabilities
-find it harder to work with line lengths exceeding 100 characters.
-It also adversely affects side-by-side diff review on typical screen
-resolutions. Long lines also make it harder to present code neatly
-in documentation or talk slides.
-
-If you're using Flake8, you can bump `max-line-length` to 88 and forget
-about it. Alternatively, use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
-B950 warning instead of E501 and keep the max line length at 80 which
-you are probably already using. You'd do it like this:
-```ini
-[flake8]
-max-line-length = 80
-...
-select = C,E,F,W,B,B950
-ignore = E501
-```
+Please refer to this document before submitting an issue. What seems like a bug might be
+intended behaviour.
+
+### Pragmatism
+
+Early versions of _Black_ used to be absolutist in some respects. They took after its
+initial author. This was fine at the time as it made the implementation simpler and
+there were not many users anyway. Not many edge cases were reported. As a mature tool,
+_Black_ does make some exceptions to rules it otherwise holds.
+
+- [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
projects / etc / vim.git / blobdiff