diff -r d05f70bfbd58 pep-0008.txt --- a/pep-0008.txt Sat Apr 16 05:23:30 2016 +1000 +++ b/pep-0008.txt Sat Apr 16 10:08:05 2016 -0400 @@ -253,31 +253,40 @@ Should a line break before or after a binary operator? ------------------------------------------------------ -For decades the recommended style has been to break after binary -operators. However, recent research 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. +For decades the recommended style was to break after binary operators. +But this can hurt readability in two ways: the operators tend to get +scattered across different columns on the screen, and each operator is +moved away from its operand and onto the previous line. Here, the eye +has to do extra work to tell which items are added and which are +subtracted:: -Some examples of code breaking before binary Boolean operators:: + # No: operators sit far away from their operands + income = (gross_wages + + taxable_interest + + (dividends - qualified_dividends) - + ira_deduction - + student_loan_interest) - class Rectangle(Blob): +To solve this readability problem, mathematicians and their publishers +follow the opposite convention. Donald Knuth explains the traditional +rule in his *Computers and Typesetting* series: "Although formulas +within a paragraph always break after binary operations and relations, +displayed formulas always break before binary operations" [3]_. - 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): - raise ValueError("sorry, you lose") - 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, - color, emphasis, highlight) +Following the tradition from mathematics usually results in more +readable code: + + # Yes: easy to match operators with operands + income = (gross_wages + + taxable_interest + + (dividends - qualified_dividends) + - ira_deduction + - student_loan_interest) + +In Python code, 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. + Blank Lines ----------- @@ -1327,7 +1336,7 @@ .. [2] Barry's GNU Mailman style guide http://barry.warsaw.us/software/STYLEGUIDE.txt -.. [3] http://rhodesmill.org/brandon/slides/2012-11-pyconca/#laying-down-the-law +.. [3] Donald Knuth's *The TeXBook*, pages 195 and 196. .. [4] http://www.wikipedia.com/wiki/CamelCase