[Python-checkins] peps: PEP-8 Update on Knuth style breaking of a long formula. #issue26780

[senthil.kumaran]

https://hg.python.org/peps/rev/9afe77ad549b
changeset:   6288:9afe77ad549b
user:        Senthil Kumaran <senthil at uthcode.com>
date:        Tue Apr 19 23:14:50 2016 -0700
summary:
  PEP-8 Update on Knuth style breaking of a long formula. #issue26780

Patch by Brandon Rhodes provides clarity and rationale for this suggestion.
Also fixes the example to use "+", "-" operators which have same precedence
level.

Reviewed by Guido van Rossum.

files:
  pep-0008.txt |  55 +++++++++++++++++++++++----------------
  1 files changed, 32 insertions(+), 23 deletions(-)


diff --git a/pep-0008.txt b/pep-0008.txt
--- a/pep-0008.txt
+++ b/pep-0008.txt
@@ -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
 

-- 
Repository URL: https://hg.python.org/peps