diff --git a/pep-0008.txt b/pep-0008.txt index a148a27af..1ad6e5200 100644 --- a/pep-0008.txt +++ b/pep-0008.txt @@ -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:: @@ -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): 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, @@ -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 @@ -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 @@ -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] Typeshed repo +.. [4] http://www.wikipedia.com/wiki/CamelCase + +.. [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