Mercurial > pylearn

comparison doc/v2_planning/API_coding_style.txt @ 1150:d7192e52653e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Moved some elements to official API
author Olivier Delalleau <delallea@iro>
date Thu, 16 Sep 2010 17:00:58 -0400
parents 2da593b0f29d
children 531e77fb67f2 a0f178bc9052
comparison
equal deleted inserted replaced
1148:2da593b0f29d 1150:d7192e52653e
5 Main Goals 5 Main Goals
6 ========== 6 ==========
7 7
8 * Code should be compatible with Python 2.4 and above (using 2to3 for 8 * Code should be compatible with Python 2.4 and above (using 2to3 for
9 conversion to Python 3.x). This may not be possible in the short term 9 conversion to Python 3.x). This may not be possible in the short term
10 for code dependent on Theano. 10 for Theano-dependent code.
11 11
12 * Code should be easy to read, understand and update by developers and 12 * Code should be easy to read, understand and update by developers and
13 users. 13 users.
14 14
15 * Code should be well-documented and well-tested. 15 * Code should be well-documented and well-tested.
21 ------------------- 21 -------------------
22 22
23 Source Material 23 Source Material
24 ~~~~~~~~~~~~~~~ 24 ~~~~~~~~~~~~~~~
25 25
26 The three main documents describing our Python coding guidelines are: 26 The four main documents describing our Python coding guidelines are:
27 * `PEP 8 -- Style Guide for Python Code 27 * `PEP 8 -- Style Guide for Python Code
28 <http://www.python.org/dev/peps/pep-0008>`_ 28 <http://www.python.org/dev/peps/pep-0008>`_
29 * `PEP 257 -- Docstring Conventions 29 * `PEP 257 -- Docstring Conventions
30 <http://www.python.org/dev/peps/pep-0257>`_ 30 <http://www.python.org/dev/peps/pep-0257>`_
31 * `Numpy Docstring Standard 31 * `Numpy Docstring Standard
37 However, there are a few points mentioned in those documents that we decided 37 However, there are a few points mentioned in those documents that we decided
38 to do differently: 38 to do differently:
39 39
40 * Use only one space (not two) after a sentence-ending period in comments. 40 * Use only one space (not two) after a sentence-ending period in comments.
41 41
42 * You do not need to add an extra blank line before the closing quotes of
43 a multi-line docstring.
44
45 .. code-block:: python
46
47 # Good.
48 """This is a multi-line docstring.
49
50 Which means it has more than one line.
51 """
52
53 # Bad.
54 """This is a multi-line docstring.
55
56 Which means it has more than one line.
57
58 """
59
42 Excerpts 60 Excerpts
43 ~~~~~~~~ 61 ~~~~~~~~
44 62
45 We emphasize here a few important topics that are found in the official 63 We emphasize here a few important topics that are found in the official
46 guidelines: 64 guidelines:
65
66 * Avoid using lists if all you care about is iterating on something. Using
67 lists:
68 - uses more memory (and possibly more CPU if the code may break out of
69 the iteration),
70 - can lead to ugly code when converted to Python 3 with 2to3,
71 - can have a different behavior if evaluating elements in the list has
72 side effects (if you want these side effects, make it explicit by
73 assigning the list to some variable before iterating on it).
74
75 +------------------------+------------------------+
76 | Iterative version | List version |
77 +========================+========================+
78 | .. code-block:: python | .. code-block:: python |
79 | | |
80 | my_dict.iterkeys | my_dict.keys |
81 | my_dict.itervalues | my_dict.values |
82 | my_dict.iteritems | my_dict.items |
83 +------------------------+------------------------+
84 | .. code-block:: python | .. code-block:: python |
85 | | |
86 | itertools.ifilter | filter |
87 | itertools.imap | map |
88 | itertools.izip | zip |
89 +------------------------+------------------------+
90 | .. code-block:: python | .. code-block:: python |
91 | | |
92 | xrange | range |
93 +------------------------+------------------------+
94
95 Code example with ``map``:
96
97 .. code-block:: python
98
99 # Good.
100 for f_x in imap(f, x):
101 ...
102 all_f_x = map(f, x)
103 map(f, x)
104 # Bad.
105 for element in map(f, x):
106 ...
107 imap(f, x)
108
109 * Generally prefer list comprehensions to ``map`` / ``filter``, as the former are
110 easier to read.
111
112 .. code-block:: python
113
114 # Good.
115 non_comments = [line.strip() for line in my_file.readlines()
116 if not line.startswith('#')]
117 # Bad.
118 non_comments = map(str.strip,
119 ifilter(lambda line: not line.startswith('#'),
120 my_file.readlines()))
121
122 * Use ``in`` on container objects instead of using class-specific methods:
123 it is easier to read and may allow you to re-use your code with different
124 container types.
125
126 .. code-block:: python
127
128 # Good.
129 has_key = key in my_dict
130 has_substring = substring in my_string
131 # Bad.
132 has_key = my_dict.has_key(key)
133 has_substring = my_string.find(substring) >= 0
134
47 135
48 Additional Recommendations 136 Additional Recommendations
49 -------------------------- 137 --------------------------
50 138
51 Things you should do even if they are not listed in official guidelines: 139 Things you should do even if they are not listed in official guidelines:
74 what is easiest to read (sometimes both can be ok). 162 what is easiest to read (sometimes both can be ok).
75 163
76 .. code-block:: python 164 .. code-block:: python
77 165
78 # Good. 166 # Good.
79 for my_very_long_variable_name in [my_food, my_bar, my_love, 167 for my_very_long_variable_name in [my_foo, my_bar, my_love,
80 my_everything]: 168 my_everything]:
81 ... 169 ...
82 for my_very_long_variable_name in [ 170 for my_very_long_variable_name in [
83 my_foo, my_bar, my_love, my_everything]: 171 my_foo, my_bar, my_love, my_everything]:
84 ... 172 ...
85 # Good iff the list needs to be frequently updated. 173 # Good iff the list needs to be frequently updated or is easier to
174 # understand when each element is on its own line.
86 for my_very_long_variable_name in [ 175 for my_very_long_variable_name in [
87 my_foo, 176 my_foo,
88 my_bar, 177 my_bar,
89 my_love, 178 my_love,
90 my_everything, 179 my_everything,
91 ]: 180 ]:
92 ... 181 ...
182 # Good as long as it does not require more than two lines.
183 for my_very_long_variable_name in [my_foo,
184 my_bar]:
185 ...
93 # Bad. 186 # Bad.
94 for my_very_long_variable_name in [my_foo, my_bar, my_love, 187 for my_very_long_variable_name in [my_foo, my_bar, my_love,
95 my_everything]: 188 my_everything]:
96 ... 189 ...
97 for my_very_long_variable_name in [my_foo, 190 for my_very_long_variable_name in [my_foo,
98 my_bar, 191 my_bar,
99 my_love, 192 my_love,
100 my_everything]: 193 my_everything]:
101 ... 194 ...
195
102 196
103 The ``logging`` Module vs. the ``warning`` Module 197 The ``logging`` Module vs. the ``warning`` Module
104 ================================================= 198 =================================================
105 199
106 The ``logging`` Module 200 The ``logging`` Module