According to Knuth, it is better to break *before* a binary operator.

This commit is contained in:
Guido van Rossum 2016-04-15 09:43:52 -07:00
parent 1a6cc45d06
commit c59c4376ad
1 changed files with 32 additions and 14 deletions

View File

@ -151,6 +151,9 @@ Acceptable options in this situation include, but are not limited to::
that_is_another_thing): that_is_another_thing):
do_something() do_something()
(Also see the discussion of whether to break before or after binary
operators below.)
The closing brace/bracket/parenthesis on multi-line constructs may The closing brace/bracket/parenthesis on multi-line constructs may
either line up under the first non-whitespace character of the last either line up under the first non-whitespace character of the last
line of list, as in:: line of list, as in::
@ -244,20 +247,33 @@ thoughts on the indentation of such multiline ``with``-statements.)
Another such case is with ``assert`` statements. Another such case is with ``assert`` statements.
Make sure to indent the continued line appropriately. The preferred Make sure to indent the continued line appropriately.
place to break around a binary operator is *after* the operator, not
before it. Some examples::
Should a line break before or after a binary operator?
------------------------------------------------------
For decades the recommended style has been to break after binary
operators. However, recent reseach unearthed recommendations by
Donald Knuth to break *before* binary operators, in his writings about
typesetting [3]_. Therefore it is permissible to break before or
after a binary operator, as long as the convention is consistent
locally. For new code Knuth's style is suggested.
Some examples of code beaking before binary Boolean operators::
class Rectangle(Blob): class Rectangle(Blob):
def __init__(self, width, height, def __init__(self, width, height,
color='black', emphasis=None, highlight=0): color='black', emphasis=None, highlight=0):
if (width == 0 and height == 0 and if (width == 0
color == 'red' and emphasis == 'strong' or and height == 0
highlight > 100): and color == 'red'
and emphasis == 'strong'
or highlight > 100):
raise ValueError("sorry, you lose") raise ValueError("sorry, you lose")
if width == 0 and height == 0 and (color == 'red' or if (width == 0 and height == 0
emphasis is None): and (color == 'red' or emphasis is None)):
raise ValueError("I don't think so -- values are %s, %s" % raise ValueError("I don't think so -- values are %s, %s" %
(width, height)) (width, height))
Blob.__init__(self, width, height, Blob.__init__(self, width, height,
@ -709,7 +725,7 @@ The following naming styles are commonly distinguished:
- ``UPPERCASE`` - ``UPPERCASE``
- ``UPPER_CASE_WITH_UNDERSCORES`` - ``UPPER_CASE_WITH_UNDERSCORES``
- ``CapitalizedWords`` (or CapWords, or CamelCase -- so named because - ``CapitalizedWords`` (or CapWords, or CamelCase -- so named because
of the bumpy look of its letters [3]_). This is also sometimes known of the bumpy look of its letters [4]_). This is also sometimes known
as StudlyCaps. as StudlyCaps.
Note: When using abbreviations in CapWords, capitalize all the Note: When using abbreviations in CapWords, capitalize all the
@ -1286,11 +1302,11 @@ annotations are changing.
PEP 484 recommends the use of stub files: .pyi files that are read PEP 484 recommends the use of stub files: .pyi files that are read
by the type checker in preference of the corresponding .py files. by the type checker in preference of the corresponding .py files.
Stub files can be distributed with a library, or separately (with Stub files can be distributed with a library, or separately (with
the library author's permission) through the typeshed repo [4]_. the library author's permission) through the typeshed repo [5]_.
- For code that needs to be backwards compatible, function annotations - For code that needs to be backwards compatible, function annotations
can be added in the form of comments. See the relevant section of can be added in the form of comments. See the relevant section of
PEP 484 [5]_. PEP 484 [6]_.
.. rubric:: Footnotes .. rubric:: Footnotes
@ -1311,12 +1327,14 @@ References
.. [2] Barry's GNU Mailman style guide .. [2] Barry's GNU Mailman style guide
http://barry.warsaw.us/software/STYLEGUIDE.txt http://barry.warsaw.us/software/STYLEGUIDE.txt
.. [3] http://www.wikipedia.com/wiki/CamelCase .. [3] http://rhodesmill.org/brandon/slides/2012-11-pyconca/#laying-down-the-law
.. [4] Typeshed repo .. [4] http://www.wikipedia.com/wiki/CamelCase
.. [5] Typeshed repo
https://github.com/python/typeshed https://github.com/python/typeshed
.. [5] Suggested syntax for Python 2.7 and straddling code .. [6] Suggested syntax for Python 2.7 and straddling code
https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code