Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1060:b4ccf6b43f27

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Added some comments about PEP8
author Olivier Delalleau <delallea@iro>
date Thu, 09 Sep 2010 12:01:49 -0400
parents 573363a9b5c7
children 64720cdca3d3
comparison
equal deleted inserted replaced
1055:bc3f7834db83 1060:b4ccf6b43f27
10 10
11 Existing Python coding style specifications and guidelines 11 Existing Python coding style specifications and guidelines
12 ---------------------------------------------------------- 12 ----------------------------------------------------------
13 13
14 * http://www.python.org/dev/peps/pep-0008/ 14 * http://www.python.org/dev/peps/pep-0008/
15 * http://www.python.org/dev/peps/pep-0257/
15 * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html 16 * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
16 * http://www.voidspace.org.uk/python/articles/python_style_guide.shtml 17 * http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
17 * http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html 18 * http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
18 * http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html 19 * http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html
19 * http://barry.warsaw.us/software/STYLEGUIDE.txt 20 * http://barry.warsaw.us/software/STYLEGUIDE.txt
28 We will probably want to take PEP-8 as starting point, and read what other 29 We will probably want to take PEP-8 as starting point, and read what other
29 people think about it / how other coding guidelines differ from it. 30 people think about it / how other coding guidelines differ from it.
30 31
31 Dumi: we should also try to find tools that automate these 32 Dumi: we should also try to find tools that automate these
32 processes: pylint, pyflakes, pychecker, pythontidy 33 processes: pylint, pyflakes, pychecker, pythontidy
34
35 OD: I think PEP8 + Google guidelines are a good basis.
36 OD: Things about PEP 8 I don't like (but it may be just me):
37
38 * If necessary, you can add an extra pair of parentheses around an
39 expression, but sometimes using a backslash looks better.
40 --> I rarely find that backslash looks better. In most situations you can
41 get rid of them. Typically I prefer:
42 if (cond_1 and
43 cond_2 and
44 cond_3):
45 to
46 if cond_1 and \
47 cond_2 and \
48 cond_3:
49
50 * You should use two spaces after a sentence-ending period.
51 --> Looks weird to me.
52
53 * Imports should usually be on separate lines
54 --> Can be a lot of lines wasted for no obvious benefit. I think this is
55 mostly useful when you import different modules from different places,
56 but I would say that for instance for standard modules it would be
57 better to import them all on a single line (doing multiple lines only
58 if there are too many of them), e.g. prefer:
59 import os, sys, time
60 to
61 import os
62 import sys
63 import time
64 However, I agree about separating imports between standard lib / 3rd
65 party, e.g. prefer:
66 import os, sys, time
67 import numpy, scipy
68 to
69 import numpy, os, scipy, sys, time
70 (Personal note: preferably order imports by alphabetical order, makes
71 it easier to quickly see if a specific module is already imported,
72 and avoids duplicated imports)
73
74 * Missing in PEP 8:
75 - How to indent multi-line statements? E.g. do we want
76 x = my_func(a, b, c,
77 d, e, f)
78 or
79 x = my_func(a, b, c,
80 d, e, f)
81 or
82 x = my_func(
83 a, b, c, d, e, f)
84 --> Probably depends on the specific situation, but we could have a
85 few typical examples (and the same happens with multi-lines lists)
86
87 * From PEP 257: The BDFL [3] recommends inserting a blank line between the
88 last paragraph in a multi-line docstring and its closing quotes, placing
89 the closing quotes on a line by themselves. This way, Emacs'
90 fill-paragraph command can be used on it.
91 --> I have nothing against Emacs, but this is ugly!
33 92
34 Documentation 93 Documentation
35 ------------- 94 -------------
36 95
37 How do we write doc? 96 How do we write doc?
50 We also need a c-style coding style. 109 We also need a c-style coding style.
51 110
52 Meetings 111 Meetings
53 -------- 112 --------
54 113
55 Next meeting: Thursday 2010/09/09, 11 am 114 * Thursday 2010/09/09, 11 am
56 115