Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1103:56c5f0990869

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: More work on some guidelines, also put some points to debate in a specific section
author Olivier Delalleau <delallea@iro>
date Mon, 13 Sep 2010 16:50:24 -0400
parents d422f726c156
children 60ef81fe1825
comparison
equal deleted inserted replaced
1102:e7c52923f122 1103:56c5f0990869
6 - Dumitru 6 - Dumitru
7 - Fred 7 - Fred
8 - David 8 - David
9 - Olivier D [leader] 9 - Olivier D [leader]
10 10
11 11 Open for public debate
12 ----------------------
13
14 * Use imports for packages and modules only. I.e. avoid
15 from foo import *
16 from foo import Bar
17 OD: Overall I agree with this. However we probably want to allow some
18 exceptions, like:
19 from itertools import imap, izip
20 Also, some people may want to have shortcuts like
21 from theano import tensor as T
22 but I would prefer to forbid this. It is handy when trying stuff in
23 the interactive interpreter, but in real code it can easily get messy
24 when you want to copy / paste different pieces of code and they use
25 different conventions. Typing tensor.* is a bit longer, but a lot more
26 portable.
27
28 * Imports should usually be on separate lines.
29 OD: I would add an exception, saying it is ok to group multiple imports
30 from the standard library on a single line, e.g.
31 import os, sys, time
32 I just don't see much benefit in putting them on separate lines (for
33 third-party imports I agree it is best to keep them separate, as it
34 makes dependencies clearer, and diffs look better when someone adds /
35 removes an import). Does anyone see a good reason to keep standard
36 library imports on different lines?
37
38 * The BDFL recommends inserting a blank line between the
39 last paragraph in a multi-line docstring and its closing quotes, placing
40 the closing quotes on a line by themselves. This way, Emacs'
41 fill-paragraph command can be used on it.
42 OD: I think it is ugly and I have not seen it used much. Any Emacs
43 user believes it is a must?
44
45 * Avoid contractions in code comments (particularly in
46 documentation): "We do not add blue to red because it does not look good"
47 rather than "We don't add blue to red because it doesn't look good".
48 OD: I mostly find it to be cleaner (been used to it while writing
49 scientific articles too).
50
51 * Imperative vs. third-person comments.
52 # Return the sum of elements in x. <-- imperative
53 # Returns the sum of elements in x. <-- third-person
54 OD: I am used to the imperative form and like it better only because it
55 typically saves one letter (the 's') and is easier to conjugate.
56
57 * OD: I like always doing the following when subclassing
58 a class A:
59 class B(A):
60 def __init__(self, b_arg_1, b_arg_2, **kw):
61 super(B, self).__init__(**kw)
62 ...
63 The point here is that the constructor always allow for extra keyword
64 arguments (except for the class at the very top of the hierarchy), which
65 are automatically passed to the parent class.
66 Pros:
67 - You do not need to repeat the parent class arguments whenever you
68 write a new subclass.
69 - Whenever you add an argument to the parent class, all child classes
70 can benefit from it without modifying their code.
71 Cons:
72 - One needs to look at the parent classes to see what these arguments
73 are.
74 - You cannot use a **kw argument in your constructor for your own
75 selfish purpose.
76 - I have no clue whether one could do this with multiple inheritance.
77 - More?
78 Question: Should we encourage this in Pylearn?
79
80 Note about warnings
81 -------------------
12 82
13 Fred: This is a refactored thing from James email of what we should put in message 83 Fred: This is a refactored thing from James email of what we should put in message
14 that we send to the user: 84 that we send to the user:
15 1) Hint where in the code this log come from. 85 1) Hint where in the code this log come from.
16 2) Hint how to hide this message? or we should this into documentation. 86 2) Hint how to hide this message? or we should this into documentation.
17 3) Tell explicitly if the user can ignore it and the consequence. 87 3) Tell explicitly if the user can ignore it and the consequence.
18 88
19 Existing Python coding style specifications and guidelines 89 Existing Python coding style specifications and guidelines
20 ---------------------------------------------------------- 90 ----------------------------------------------------------
21 91
22 * http://www.python.org/dev/peps/pep-0008/ Style Guide for Python Code 92 * Must-read
23 * http://www.python.org/dev/peps/pep-0257/ Docstring Conventions 93 * Official Python coding style guide: http://www.python.org/dev/peps/pep-0008
24 * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html Google Python Style Guide 94 * Official docstring conventions: http://www.python.org/dev/peps/pep-0257
25 * http://www.voidspace.org.uk/python/articles/python_style_guide.shtml 95 * Google Python Style Guide: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
26 * http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html 96 * Interesting
27 * http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html 97 * Code Like a Pythonista: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
28 * http://barry.warsaw.us/software/STYLEGUIDE.txt 98 * Can skip
29 * http://self.maluke.com/style 99 * Python style for university class: http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html
30 * http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines 100 * Mailman coding style: http://barry.warsaw.us/software/STYLEGUIDE.txt
31 * http://lists.osafoundation.org/pipermail/dev/2003-March/000479.html 101 * Some company coding style: http://self.maluke.com/style
32 * http://learnpython.pbworks.com/PythonTricks 102 * Chandler coding style: http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines
33 * http://eikke.com/how-not-to-write-python-code/ 103 * Outdated recommendations: http://lists.osafoundation.org/pipermail/dev/2003-March/000479.html
34 * http://jaynes.colorado.edu/PythonGuidelines.html 104 * Mostly some beginners tips: http://learnpython.pbworks.com/PythonTricks
35 * http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style 105 * More beginners tips: http://eikke.com/how-not-to-write-python-code/
36 * http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines 106 * Cogent coding guidelines: http://jaynes.colorado.edu/PythonGuidelines.html
107 * Djangoo coding guidelines: http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
108 * Numpy documentation style guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
109 * Some random guy guidelines (nothing special): http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
37 110
38 We will probably want to take PEP-8 as starting point, and read what other 111 We will probably want to take PEP-8 as starting point, and read what other
39 people think about it / how other coding guidelines differ from it. 112 people think about it / how other coding guidelines differ from it.
40 113
41 Dumi: we should also try to find tools that automate these 114 Dumi: we should also try to find tools that automate these
59 --> Looks weird to me. 132 --> Looks weird to me.
60 (DWF: This is an old convention from the typewriter era. It has more 133 (DWF: This is an old convention from the typewriter era. It has more
61 or less been wiped out by HTML's convention of ignoring extra 134 or less been wiped out by HTML's convention of ignoring extra
62 whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for 135 whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for
63 more detail. I think it's okay to drop this convention in source code.) 136 more detail. I think it's okay to drop this convention in source code.)
64 137 OD: Cool, thanks, I guess we can drop it then.
65 * Imports should usually be on separate lines
66 --> Can be a lot of lines wasted for no obvious benefit. I think this is
67 mostly useful when you import different modules from different places,
68 but I would say that for instance for standard modules it would be
69 better to import them all on a single line (doing multiple lines only
70 if there are too many of them), e.g. prefer:
71 import os, sys, time
72 to
73 import os
74 import sys
75 import time
76 However, I agree about separating imports between standard lib / 3rd
77 party, e.g. prefer:
78 import os, sys, time
79 import numpy, scipy
80 to
81 import numpy, os, scipy, sys, time
82 (Personal note: preferably order imports by alphabetical order, makes
83 it easier to quickly see if a specific module is already imported,
84 and avoids duplicated imports)
85 138
86 * Missing in PEP 8: 139 * Missing in PEP 8:
87 - How to indent multi-line statements? E.g. do we want 140 - How to indent multi-line statements? E.g. do we want
88 x = my_func(a, b, c, 141 x = my_func(a, b, c,
89 d, e, f) 142 d, e, f)
99 indent is broken after a paranthesis then at any point. 152 indent is broken after a paranthesis then at any point.
100 OD: After thinking about it, I agreee as well. My recommendation would 153 OD: After thinking about it, I agreee as well. My recommendation would
101 be to go with 2 when it can fit on two lines, and 3 otherwise. Same 154 be to go with 2 when it can fit on two lines, and 3 otherwise. Same
102 with lists. 155 with lists.
103 156
104 * From PEP 257: The BDFL [3] recommends inserting a blank line between the
105 last paragraph in a multi-line docstring and its closing quotes, placing
106 the closing quotes on a line by themselves. This way, Emacs'
107 fill-paragraph command can be used on it.
108 --> I have nothing against Emacs, but this is ugly!
109
110 Documentation 157 Documentation
111 ------------- 158 -------------
112 159
113 How do we write doc? 160 How do we write doc?
114 161
134 181
135 * Documentation 182 * Documentation
136 Use RST with Sphinx. 183 Use RST with Sphinx.
137 Task: Provide specific examples on how to document a class, method, and some 184 Task: Provide specific examples on how to document a class, method, and some
138 specific classes like Op (DE). Modify the theano documentation to include that. 185 specific classes like Op (DE). Modify the theano documentation to include that.
186 OD: May want to check out
187 http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
139 188
140 * Python versions to be supported 189 * Python versions to be supported
141 Support 2.4 (because some of the clusters are still running 2.4) and write 190 Support 2.4 (because some of the clusters are still running 2.4) and write
142 code that can be converted to 3.x with 2to3 in a straightforward way. 191 code that can be converted to 3.x with 2to3 in a straightforward way.
143 Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD) 192 Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
179 Suggestion by PV 228 Suggestion by PV
180 ---------------- 229 ----------------
181 230
182 Have a sample code that showcases everything one should comply to. 231 Have a sample code that showcases everything one should comply to.
183 232
184 Some coding guidlines (work-in-progress from OD) 233 Some coding guidelines (work-in-progress from OD)
185 ------------------------------------------------ 234 -------------------------------------------------
186 235
187 * Avoid using lists if all you care about is iterating on something. Using 236 * Avoid using lists if all you care about is iterating on something. Using
188 lists: 237 lists:
189 - uses more memory (and possibly more CPU if the code may break out of 238 - uses more memory (and possibly more CPU if the code may break out of
190 the iteration) 239 the iteration)
209 Yes No 258 Yes No
210 --- -- 259 --- --
211 key in my_dict my_dict.has_key(key) 260 key in my_dict my_dict.has_key(key)
212 sub_string in my_string my_string.find(sub_string) >= 0 261 sub_string in my_string my_string.find(sub_string) >= 0
213 262
214 * (Point to debate) Avoid contractions in code comments (particularly in
215 documentation): "We do not add blue to red because it does not look
216 good" rather than "We don't add blue to red because it doesn't look
217 good". I mostly find it to be cleaner (been used to it while writing
218 scientific articles too).
219
220 * (Point to debate) Imperative vs. third-person comments. I am used to the
221 imperative form and like it better only because it typically saves one
222 letter (the 's'): "Return the sum of elements in x" rather than
223 "Returns the sum of elements in x".
224
225 * (Point to debate) I like always doing the following when subclassing
226 a class A:
227 class B(A):
228 def __init__(self, b_arg_1, b_arg_2, **kw):
229 super(B, self).__init__(**kw)
230 ...
231 The point here is that the constructor always allow for extra keyword
232 arguments (except for the class at the very top of the hierarchy), which
233 are automatically passed to the parent class.
234 Pros:
235 - You do not need to repeat the parent class arguments whenever you
236 write a new subclass.
237 - Whenever you add an argument to the parent class, all child classes
238 can benefit from it without modifying their code.
239 Cons:
240 - One needs to look at the parent classes to see what these arguments
241 are.
242 - You cannot use a **kw argument in your constructor for your own
243 selfish purpose.
244 - I have no clue whether one could do this with multiple inheritance.
245 - More?
246 Question: Should we encourage this in Pylearn?
247 263
248 * Generally prefer list comprehensions to map / filter, as the former are 264 * Generally prefer list comprehensions to map / filter, as the former are
249 easier to read. 265 easier to read.
250 Yes: 266 Yes:
251 non_comments = [line.strip() for line in my_file.readlines() 267 non_comments = [line.strip() for line in my_file.readlines()
270 286
271 * Only use ASCII characters in code files. 287 * Only use ASCII characters in code files.
272 288
273 * Code indent must be done with four blank characters (not with tabs). 289 * Code indent must be done with four blank characters (not with tabs).
274 290
291 * Limit lines to 79 characters.
292
293 * Comments should start with a capital letter (unless the first word is a
294 code identifier) and end with a period (very short inline comments may
295 ignore this rule).
296
275 * Whenever you read / write binary files, specify it in the mode ('rb' for 297 * Whenever you read / write binary files, specify it in the mode ('rb' for
276 reading, 'wb' for writing). This is important for cross-platform and 298 reading, 'wb' for writing). This is important for cross-platform and
277 Python 3 compatibility (e.g. when pickling / unpickling objects). 299 Python 3 compatibility (e.g. when pickling / unpickling objects).
278 300
279 * Avoid tuple parameter unpacking to avoid very ugly code when converting 301 * Avoid tuple parameter unpacking to avoid very ugly code when converting
288 310
289 * Always raise exception with 311 * Always raise exception with
290 raise MyException(args) 312 raise MyException(args)
291 where MyException inherits from Exception. 313 where MyException inherits from Exception.
292 314
315 * Imports should be listed in alphabetical order. It makes it easier to
316 verify that something is imported, and avoids duplicated imports.
317
318 * Use a leading underscore '_' for internal attributes / methods,
319 but avoid the double underscore '__' unless you know what you are
320 doing.
321
322 * A script's only top-level code should be something like:
323 if __name__ == '__main__':
324 sys.exit(main())
325
293 Mercurial commits 326 Mercurial commits
294 ----------------- 327 -----------------
295 328
296 * How to write good commit messages? 329 * How to write good commit messages?
330 OD: Check Django's guidelines (link above)
297 * Standardize the merge commit text (what is the message from fetch?) 331 * Standardize the merge commit text (what is the message from fetch?)
298 332
333