Mercurial > pylearn

annotate doc/v2_planning/coding_style.txt @ 1113:60ef81fe1825

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
2cents in coding_style
author James Bergstra <bergstrj@iro.umontreal.ca>
date Tue, 14 Sep 2010 13:30:02 -0400
parents 56c5f0990869
children 1a1c0c3adcca
rev   line source
1009
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
1 Discussion of Coding-Style
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
2 ==========================
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
3
1017
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
4 Participants
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
5 ------------
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
6 - Dumitru
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
7 - Fred
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
8 - David
1028
c6a74b24330b coding_style: Olivier D confirmed as leader
Olivier Delalleau <delallea@iro>
parents: 1025
diff changeset
9 - Olivier D [leader]
1017
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
10
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
11 Open for public debate
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
12 ----------------------
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
13
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
14 * Use imports for packages and modules only. I.e. avoid
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
15 from foo import *
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
16 from foo import Bar
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
17 OD: Overall I agree with this. However we probably want to allow some
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
18 exceptions, like:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
19 from itertools import imap, izip
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
20 Also, some people may want to have shortcuts like
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
21 from theano import tensor as T
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
22 but I would prefer to forbid this. It is handy when trying stuff in
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
23 the interactive interpreter, but in real code it can easily get messy
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
24 when you want to copy / paste different pieces of code and they use
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
25 different conventions. Typing tensor.* is a bit longer, but a lot more
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
26 portable.
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
27 JB: I thought that these are nice:
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
28 - "from foo import Bar"
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
29 - "from foo import Bar, Blah"
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
30 What's wrong with them? They keep the code listing short and readable.
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
31 I would discourage these forms when symbols 'Bar' and 'Blah' are
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
32 ambiguous, in which case the parent module prefix serves to disambiguate
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
33 them in the code.
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
34 I agree that the "import A as B" form should be discouraged in general,
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
35 because that's just confusing and makes code less grep-friendly.
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
36
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
37 * Imports should usually be on separate lines.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
38 OD: I would add an exception, saying it is ok to group multiple imports
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
39 from the standard library on a single line, e.g.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
40 import os, sys, time
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
41 I just don't see much benefit in putting them on separate lines (for
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
42 third-party imports I agree it is best to keep them separate, as it
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
43 makes dependencies clearer, and diffs look better when someone adds /
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
44 removes an import). Does anyone see a good reason to keep standard
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
45 library imports on different lines?
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
46 JB: what does 'usually' mean here? The guideline seems vacuous.
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
47
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
48 * The BDFL recommends inserting a blank line between the
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
49 last paragraph in a multi-line docstring and its closing quotes, placing
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
50 the closing quotes on a line by themselves. This way, Emacs'
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
51 fill-paragraph command can be used on it.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
52 OD: I think it is ugly and I have not seen it used much. Any Emacs
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
53 user believes it is a must?
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
54
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
55 * Avoid contractions in code comments (particularly in
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
56 documentation): "We do not add blue to red because it does not look good"
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
57 rather than "We don't add blue to red because it doesn't look good".
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
58 OD: I mostly find it to be cleaner (been used to it while writing
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
59 scientific articles too).
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
60 JB: +1
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
61
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
62 * Imperative vs. third-person comments.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
63 # Return the sum of elements in x. <-- imperative
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
64 # Returns the sum of elements in x. <-- third-person
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
65 OD: I am used to the imperative form and like it better only because it
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
66 typically saves one letter (the 's') and is easier to conjugate.
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
67 JB: What about being compatible with markup formats that have a :returns:
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
68 tag?
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
69
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
70 * OD: I like always doing the following when subclassing
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
71 a class A:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
72 class B(A):
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
73 def __init__(self, b_arg_1, b_arg_2, **kw):
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
74 super(B, self).__init__(**kw)
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
75 ...
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
76 The point here is that the constructor always allow for extra keyword
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
77 arguments (except for the class at the very top of the hierarchy), which
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
78 are automatically passed to the parent class.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
79 Pros:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
80 - You do not need to repeat the parent class arguments whenever you
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
81 write a new subclass.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
82 - Whenever you add an argument to the parent class, all child classes
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
83 can benefit from it without modifying their code.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
84 Cons:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
85 - One needs to look at the parent classes to see what these arguments
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
86 are.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
87 - You cannot use a **kw argument in your constructor for your own
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
88 selfish purpose.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
89 - I have no clue whether one could do this with multiple inheritance.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
90 - More?
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
91 Question: Should we encourage this in Pylearn?
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
92
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
93 JB: +0.5
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
94
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
95 * JB: How should we combine capitalization and underscores to name classes
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
96 and functions related to an algorithm like 'SGD' or a model like 'RBM'
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
97 whose common name is capitalized? Case in point: How should I name a
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
98 Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation?
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
99
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
100 Note about warnings
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
101 -------------------
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
102
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
103 Fred: This is a refactored thing from James email of what we should put in message
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
104 that we send to the user:
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
105 1) Hint where in the code this log come from.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
106 2) Hint how to hide this message? or we should this into documentation.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
107 3) Tell explicitly if the user can ignore it and the consequence.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
108
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
109 Existing Python coding style specifications and guidelines
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
110 ----------------------------------------------------------
1017
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
111
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
112 * Must-read
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
113 * Official Python coding style guide: http://www.python.org/dev/peps/pep-0008
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
114 * Official docstring conventions: http://www.python.org/dev/peps/pep-0257
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
115 * Google Python Style Guide: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
116 * Interesting
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
117 * Code Like a Pythonista: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
118 * Can skip
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
119 * Python style for university class: http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
120 * Mailman coding style: http://barry.warsaw.us/software/STYLEGUIDE.txt
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
121 * Some company coding style: http://self.maluke.com/style
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
122 * Chandler coding style: http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
123 * Outdated recommendations: http://lists.osafoundation.org/pipermail/dev/2003-March/000479.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
124 * Mostly some beginners tips: http://learnpython.pbworks.com/PythonTricks
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
125 * More beginners tips: http://eikke.com/how-not-to-write-python-code/
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
126 * Cogent coding guidelines: http://jaynes.colorado.edu/PythonGuidelines.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
127 * Djangoo coding guidelines: http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
128 * Numpy documentation style guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
129 * Some random guy guidelines (nothing special): http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
1009
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
130
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
131 We will probably want to take PEP-8 as starting point, and read what other
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
132 people think about it / how other coding guidelines differ from it.
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
133
1050
573363a9b5c7 more tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1049
diff changeset
134 Dumi: we should also try to find tools that automate these
573363a9b5c7 more tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1049
diff changeset
135 processes: pylint, pyflakes, pychecker, pythontidy
1049
ff9361e39c97 remark on fiding tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1033
diff changeset
136
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
137 OD: Things about PEP 8 I don't like (but it may be just me):
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
138
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
139 * If necessary, you can add an extra pair of parentheses around an
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
140 expression, but sometimes using a backslash looks better.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
141 --> I rarely find that backslash looks better. In most situations you can
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
142 get rid of them. Typically I prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
143 if (cond_1 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
144 cond_2 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
145 cond_3):
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
146 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
147 if cond_1 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
148 cond_2 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
149 cond_3:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
150
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
151 * You should use two spaces after a sentence-ending period.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
152 --> Looks weird to me.
1063
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
153 (DWF: This is an old convention from the typewriter era. It has more
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
154 or less been wiped out by HTML's convention of ignoring extra
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
155 whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
156 more detail. I think it's okay to drop this convention in source code.)
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
157 OD: Cool, thanks, I guess we can drop it then.
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
158
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
159 * Missing in PEP 8:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
160 - How to indent multi-line statements? E.g. do we want
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
161 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
162 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
163 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
164 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
165 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
166 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
167 x = my_func(
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
168 a, b, c, d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
169 --> Probably depends on the specific situation, but we could have a
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
170 few typical examples (and the same happens with multi-lines lists)
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
171 (Fred: I would do 2 or 3, but not 1. I find it more redable when the
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
172 indent is broken after a paranthesis then at any point.
1075
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
173 OD: After thinking about it, I agreee as well. My recommendation would
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
174 be to go with 2 when it can fit on two lines, and 3 otherwise. Same
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
175 with lists.
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
176
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
177 Documentation
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
178 -------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
179
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
180 How do we write doc?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
181
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
182 Compatibility with various Python versions
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
183 ------------------------------------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
184
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
185 * Which Python 2.x version do we want to support?
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
186
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
187 * Is it reasonable to have coding guidelines that would make the code as
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
188 compatible as possible with Python 3?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
189
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
190 C coding style
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
191 --------------
1022
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
192
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
193 We also need a c-style coding style.
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
194
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
195 Meeting 2010/09/09
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
196 ------------------
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
197
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
198 * Coding guidelines
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
199 PEP 8 & Google should be a good basis to start with.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
200 Task: Highlight the most important points in them (OD).
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
201
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
202 * Documentation
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
203 Use RST with Sphinx.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
204 Task: Provide specific examples on how to document a class, method, and some
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
205 specific classes like Op (DE). Modify the theano documentation to include that.
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
206 OD: May want to check out
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
207 http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
208
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
209 * Python versions to be supported
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
210 Support 2.4 (because some of the clusters are still running 2.4) and write
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
211 code that can be converted to 3.x with 2to3 in a straightforward way.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
212 Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
1063
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
213 (DWF: Pauli Virtanen and others have put together extensive
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
214 documentation in the process of porting NumPy to Py3K, see his notes at
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
215 http://projects.scipy.org/numpy/browser/trunk/doc/Py3K.txt -- this is
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
216 the most complete resource for complicated combinations of Python and C).
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
217
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
218
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
219 * C coding style
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
220 How to write C code (in particular for Numpy / Cuda), and how to mix C and
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
221 Python.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
222 Task: See if there would be a sensible C code style to follow (maybe look how
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
223 Numpy does it), and how projects that mix C and Python deal with it (e.g. use
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
224 separate files, or be able to have mixed syntax highlighting?) (FB)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
225
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
226 * Program output
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
227 Use the warning and logging modules. Avoid print as much as possible.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
228 Task: Look into these modules to define general guidelines e.g. to decide when
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
229 to use warning instead of logging. (DWF)
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
230
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
231 * Automatized code verification
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
232 Use pychecker & friends to make sure everything is fine.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
233 Task: Look into the various options available (DE)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
234
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
235 * Tests
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
236 Force people to write tests. Automatic email reminder of code lines not
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
237 covered by tests (see if we can get this from nosetests). Decorator to mark
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
238 some classes / methods as not being tested yet, so as to be able to
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
239 automatically warn the user when he is using untested stuff (and to remind
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
240 ourselves we should add a test).
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
241 Task: See feasibility. (OD)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
242
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
243 * VIM / Emacs plugins / config files
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
244 To enforce good coding style automatically.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
245 Task: Look for existing options. (FB)
1063
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
246 (DWF: I have put some time into this for vim, I will send around my files)
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
247
1066
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
248 Suggestion by PV
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
249 ----------------
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
250
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
251 Have a sample code that showcases everything one should comply to.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
252
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
253 Some coding guidelines (work-in-progress from OD)
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
254 -------------------------------------------------
1066
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
255
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
256 * Avoid using lists if all you care about is iterating on something. Using
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
257 lists:
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
258 - uses more memory (and possibly more CPU if the code may break out of
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
259 the iteration)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
260 - can lead to ugly code when converted to Python 3 with 2to3
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
261 - can have a different behavior if evaluating elements in the list has
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
262 side effects (if you want these side effects, make it explicit by
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
263 assigning the list to some variable before iterating on it)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
264
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
265 Iterative version List version
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
266 my_dict.iterkeys() my_dict.keys()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
267 my_dict.itervalues() my_dict.values()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
268 my_dict.iteritems() my_dict.items()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
269 itertools.imap map
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
270 itertools.ifilter filter
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
271 itertools.izip zip
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
272 xrange range
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
273
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
274 * Use `in` on container objects instead of using class-specific methods.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
275 It is easier to read and may allow you to use your code with different
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
276 container types.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
277
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
278 Yes No
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
279 --- --
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
280 key in my_dict my_dict.has_key(key)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
281 sub_string in my_string my_string.find(sub_string) >= 0
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
282
1073
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
283
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
284 * Generally prefer list comprehensions to map / filter, as the former are
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
285 easier to read.
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
286 Yes:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
287 non_comments = [line.strip() for line in my_file.readlines()
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
288 if not line.startswith('#')]
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
289 No:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
290 non_comments = map(str.strip,
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
291 filter(lambda line: not line.startswith('#'),
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
292 my_file.readlines()))
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
293
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
294 * Use the `key` argument instead of `cmp` when sorting (for Python 3
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
295 compatibility).
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
296 Yes:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
297 my_list.sort(key=abs)
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
298 No:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
299 my_list.sort(cmp=lambda x, y: cmp(abs(x), abs(y)))
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
300
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
301 * Use // for integer division (for readability and Python 3 compatibility).
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
302 Yes:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
303 n_samples_per_split = n_samples // n_splits
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
304 No:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
305 n_samples_per_split = n_samples / n_splits
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
306
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
307 * Only use ASCII characters in code files.
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
308
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
309 * Code indent must be done with four blank characters (not with tabs).
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
310
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
311 * Limit lines to 79 characters.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
312
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
313 * Comments should start with a capital letter (unless the first word is a
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
314 code identifier) and end with a period (very short inline comments may
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
315 ignore this rule).
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
316
1073
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
317 * Whenever you read / write binary files, specify it in the mode ('rb' for
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
318 reading, 'wb' for writing). This is important for cross-platform and
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
319 Python 3 compatibility (e.g. when pickling / unpickling objects).
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
320
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
321 * Avoid tuple parameter unpacking to avoid very ugly code when converting
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
322 to Python 3.
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
323 Yes:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
324 def f(x, y_z):
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
325 y, z = y_z
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
326 No:
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
327 def f(x, (y, z))
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
328
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
329 * Only use cPickle, not pickle.
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
330
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
331 * Always raise exception with
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
332 raise MyException(args)
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
333 where MyException inherits from Exception.
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
334
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
335 * Imports should be listed in alphabetical order. It makes it easier to
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
336 verify that something is imported, and avoids duplicated imports.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
337
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
338 * Use a leading underscore '_' for internal attributes / methods,
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
339 but avoid the double underscore '__' unless you know what you are
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
340 doing.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
341
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
342 * A script's only top-level code should be something like:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
343 if __name__ == '__main__':
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
344 sys.exit(main())
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
345
1075
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
346 Mercurial commits
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
347 -----------------
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
348
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
349 * How to write good commit messages?
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
350 OD: Check Django's guidelines (link above)
1075
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
351 * Standardize the merge commit text (what is the message from fetch?)
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
352
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
353