@@ -151,6 +151,9 @@ Acceptable options in this situation include, but are not limited to::
151
151
that_is_another_thing):
152
152
do_something()
153
153
154
+ (Also see the discussion of whether to break before or after binary
155
+ operators below.)
156
+
154
157
The closing brace/bracket/parenthesis on multi-line constructs may
155
158
either line up under the first non-whitespace character of the last
156
159
line of list, as in::
@@ -244,20 +247,33 @@ thoughts on the indentation of such multiline ``with``-statements.)
244
247
245
248
Another such case is with ``assert`` statements.
246
249
247
- Make sure to indent the continued line appropriately. The preferred
248
- place to break around a binary operator is *after* the operator, not
249
- before it. Some examples::
250
+ Make sure to indent the continued line appropriately.
251
+
252
+
253
+ Should a line break before or after a binary operator?
254
+ ------------------------------------------------------
255
+
256
+ For decades the recommended style has been to break after binary
257
+ operators. However, recent reseach unearthed recommendations by
258
+ Donald Knuth to break *before* binary operators, in his writings about
259
+ typesetting [3]_. Therefore it is permissible to break before or
260
+ after a binary operator, as long as the convention is consistent
261
+ locally. For new code Knuth's style is suggested.
262
+
263
+ Some examples of code beaking before binary Boolean operators::
250
264
251
265
class Rectangle(Blob):
252
266
253
267
def __init__(self, width, height,
254
268
color='black', emphasis=None, highlight=0):
255
- if (width == 0 and height == 0 and
256
- color == 'red' and emphasis == 'strong' or
257
- highlight > 100):
269
+ if (width == 0
270
+ and height == 0
271
+ and color == 'red'
272
+ and emphasis == 'strong'
273
+ or highlight > 100):
258
274
raise ValueError("sorry, you lose")
259
- if width == 0 and height == 0 and (color == 'red' or
260
- emphasis is None):
275
+ if ( width == 0 and height == 0
276
+ and (color == 'red' or emphasis is None) ):
261
277
raise ValueError("I don't think so -- values are %s, %s" %
262
278
(width, height))
263
279
Blob.__init__(self, width, height,
@@ -709,7 +725,7 @@ The following naming styles are commonly distinguished:
709
725
- ``UPPERCASE``
710
726
- ``UPPER_CASE_WITH_UNDERSCORES``
711
727
- ``CapitalizedWords`` (or CapWords, or CamelCase -- so named because
712
- of the bumpy look of its letters [3 ]_). This is also sometimes known
728
+ of the bumpy look of its letters [4 ]_). This is also sometimes known
713
729
as StudlyCaps.
714
730
715
731
Note: When using abbreviations in CapWords, capitalize all the
@@ -1286,11 +1302,11 @@ annotations are changing.
1286
1302
PEP 484 recommends the use of stub files: .pyi files that are read
1287
1303
by the type checker in preference of the corresponding .py files.
1288
1304
Stub files can be distributed with a library, or separately (with
1289
- the library author's permission) through the typeshed repo [4 ]_.
1305
+ the library author's permission) through the typeshed repo [5 ]_.
1290
1306
1291
1307
- For code that needs to be backwards compatible, function annotations
1292
1308
can be added in the form of comments. See the relevant section of
1293
- PEP 484 [5 ]_.
1309
+ PEP 484 [6 ]_.
1294
1310
1295
1311
1296
1312
.. rubric:: Footnotes
@@ -1311,12 +1327,14 @@ References
1311
1327
.. [2] Barry's GNU Mailman style guide
1312
1328
http://barry.warsaw.us/software/STYLEGUIDE.txt
1313
1329
1314
- .. [3] http://www.wikipedia.com/wiki/CamelCase
1330
+ .. [3] http://rhodesmill.org/brandon/slides/2012-11-pyconca/#laying-down-the-law
1331
+
1332
+ .. [4] http://www.wikipedia.com/wiki/CamelCase
1315
1333
1316
- .. [4 ] Typeshed repo
1334
+ .. [5 ] Typeshed repo
1317
1335
https://github.com/python/typeshed
1318
1336
1319
- .. [5 ] Suggested syntax for Python 2.7 and straddling code
1337
+ .. [6 ] Suggested syntax for Python 2.7 and straddling code
1320
1338
https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
1321
1339
1322
1340
0 commit comments