Skip to content

Commit

Permalink
According to Knuth, it is better to break *before* a binary operator.
Browse files Browse the repository at this point in the history
  • Loading branch information
gvanrossum committed Apr 15, 2016
1 parent 1a6cc45 commit c59c437
Showing 1 changed file with 32 additions and 14 deletions.
46 changes: 32 additions & 14 deletions pep-0008.txt
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,9 @@ Acceptable options in this situation include, but are not limited to::
that_is_another_thing):
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
either line up under the first non-whitespace character of the last
line of list, as in::
Expand Down Expand Up @@ -244,20 +247,33 @@ thoughts on the indentation of such multiline ``with``-statements.)

Another such case is with ``assert`` statements.

Make sure to indent the continued line appropriately. The preferred
place to break around a binary operator is *after* the operator, not
before it. Some examples::
Make sure to indent the continued line appropriately.


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):

def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if (width == 0 and height == 0 and
color == 'red' and emphasis == 'strong' or
highlight > 100):
if (width == 0
and height == 0
and color == 'red'
and emphasis == 'strong'
or highlight > 100):

This comment has been minimized.

Copy link
@billytetrud

billytetrud Apr 28, 2022

Having the 'or' alongside those ands looks odd to me. In such a case, I'd prefer surrounding the group of ands with extra parens, for clarity. This is how flake makes that look:

if (
    width == 0 and height == 0 and color == "red" and emphasis == "strong"
) or highlight > 100:

This comment has been minimized.

Copy link
@Rosuav

Rosuav Apr 28, 2022

Contributor

This isn't really a good place to discuss this sort of thing. If you want the PEP to be changed, start by discussing the matter on one of the mailing lists - most people don't keep an eye on comments on old commits.

raise ValueError("sorry, you lose")
if width == 0 and height == 0 and (color == 'red' or
emphasis is None):
if (width == 0 and height == 0
and (color == 'red' or emphasis is None)):
raise ValueError("I don't think so -- values are %s, %s" %
(width, height))
Blob.__init__(self, width, height,
Expand Down Expand Up @@ -709,7 +725,7 @@ The following naming styles are commonly distinguished:
- ``UPPERCASE``
- ``UPPER_CASE_WITH_UNDERSCORES``
- ``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.

Note: When using abbreviations in CapWords, capitalize all the
Expand Down Expand Up @@ -1286,11 +1302,11 @@ annotations are changing.
PEP 484 recommends the use of stub files: .pyi files that are read
by the type checker in preference of the corresponding .py files.
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
can be added in the form of comments. See the relevant section of
PEP 484 [5]_.
PEP 484 [6]_.


.. rubric:: Footnotes
Expand All @@ -1311,12 +1327,14 @@ References
.. [2] Barry's GNU Mailman style guide
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] http://www.wikipedia.com/wiki/CamelCase

.. [4] Typeshed repo
.. [5] Typeshed repo
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


Expand Down

0 comments on commit c59c437

Please sign in to comment.