Unverified Commit 6b935a34 authored by Łukasz Langa's avatar Łukasz Langa
Browse files

Clarify current trailing comma behavior in the docs

parent 1af648d0
Loading
Loading
Loading
Loading
+4 −10
Changes for docs/the_black_code_style.md: 4 added lines, 10 removed lines.
Original line number Diff line number Diff line
@@ -244,16 +244,6 @@ required due to an inner function starting immediately after.
_Black_ will add trailing commas to expressions that are split by comma where each
element is on its own line. This includes function signatures.

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. Moreover, in
this scenario, if you added another argument to your call, you'd probably fit it in the
same line anyway. That doesn't make diffs any larger.

One exception to removing trailing commas is tuple expressions with just one element. In
this case _Black_ won't touch the single trailing comma as this would unexpectedly
change the underlying data type. Note that this is also the case when commas are used
while indexing. This is a tuple in disguise: `numpy_array[3, ]`.

One exception to adding trailing commas is function signatures containing `*`, `*args`,
or `**kwargs`. In this case a trailing comma is only safe to use on Python 3.6. _Black_
will detect if your file is already 3.6+ only and use trailing commas in this situation.
@@ -262,6 +252,10 @@ in function signatures that have stars in them. In other words, if you'd like a
comma in this situation and _Black_ didn't recognize it was safe to do so, put it there
manually and _Black_ will keep it.

A pre-existing trailing comma informs _Black_ to always explode contents of the current
bracket pair into one item per line. Read more about this in the
[Pragmatism](#pragmatism) section below.

### Strings

_Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It