[issue11425] Cleanup sample codes in tutorial.
New submission from INADA Naoki songofacandy@gmail.com:
* Insert spaces around operators and after commas. * Split one liner blocks (ex. def foo(x, y): return x + y) to multi-line blocks. * Insert empty line after def block for scripts (not interactive mode). * Use new-style raise (s/ralse KeyboardInterrupt/raise KeyboardInterrupt()/) * Use x ** 3 instead of x * x * x.
Attached patch is for Python 2.6. I'll make same changes for Python 3.1 if this patch is accepted.
---------- assignee: docs@python components: Documentation files: cleanup_tutorial_codes.patch keywords: patch messages: 130225 nosy: docs@python, naoki priority: normal severity: normal status: open title: Cleanup sample codes in tutorial. versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file21027/cleanup_tutorial_codes.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11425 _______________________________________
INADA Naoki songofacandy@gmail.com added the comment:
This patch inserts spaces around ** operator but I prefer no spaces around **. Any thoughts?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11425 _______________________________________
Raymond Hettinger rhettinger@users.sourceforge.net added the comment:
Sorry, but I think many of these changes should not be made.
Sometime the tight spacing is used for visual grouping. The following look fine and should not be changed because adding spaces around the + or * operator makes the whole sentence harder to mentally parse correctly:
sum(x*y for x,y in zip(xvec, yvec)) a, b = b, a+b
Also, it is perfectly correct to use: raise StopIteration We use the parentheses when there is an argument: raise KeyError('key not found: {!r}'.format(k))
Sometimes one-liners are okay in the interactive mode for quick filter functions and whatnot. Spreading them out with '...' lines makes the example harder to follow and expands the set-up part of the example rather than the part being explained.
It's perfectly valid to use x * x * x instead of x**3 in an example of how to use map. We want the example to be as simple as possible.
Also, the interactive prompt examples should be left as-is. They communicate the free-form nature of experimentation at the prompt.
---------- nosy: +rhettinger resolution: -> rejected status: open -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11425 _______________________________________
Georg Brandl georg@python.org added the comment:
I made the c -> cls change in 88fe1ac48460. Some other fixes have already been made in py3k (like removing the duplicate index keyword), and for the others I completely agree with Raymond.
---------- nosy: +georg.brandl resolution: rejected -> fixed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11425 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Just two notes: The operations like “7205759403792794 * 10**30 / 2**56” in floatimport could use some parens; the patch removed a duplicate “statement: for” entry.
---------- nosy: +eric.araujo
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11425 _______________________________________
Change by Chas Belov docorbit@sonic.net:
---------- title: Cleanup sample codes in tutorial. -> Cleanup sample code spacing and block arrangement in tutorial.
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue11425 _______________________________________
participants (5)
-
Chas Belov -
Georg Brandl
-
INADA Naoki
-
Raymond Hettinger
-
Éric Araujo