Mercurial > pylearn

comparison doc/v2_planning/API_coding_style.txt @ 1162:4f1b9e0a1377

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Moved more stuff to API
author Olivier Delalleau <delallea@iro>
date Fri, 17 Sep 2010 12:56:30 -0400
parents 531e77fb67f2
children 53340a8df1fa
comparison
equal deleted inserted replaced
1160:8b65a1b27b94 1162:4f1b9e0a1377
1 ========================= 1 =========================
2 Coding Style Guidelines 2 Coding Style Guidelines
3 ========================= 3 =========================
4
5 Note: until the Pylearn documentation is properly compiled, you can view
6 the HTML version of this document `here
7 <http://www.iro.umontreal.ca/~delallea/tmp/coding_style/html/API_coding_style.html>`_.
4 8
5 Main Goals 9 Main Goals
6 ========== 10 ==========
7 11
8 * Code should be compatible with Python 2.4 and above (using 2to3 for 12 * Code should be compatible with Python 2.4 and above (using 2to3 for
55 59
56 Which means it has more than one line. 60 Which means it has more than one line.
57 61
58 """ 62 """
59 63
64 * Standard library imports can (and should) be on the same line, to avoid
65 wasting space on straighforward imports:
66
67 .. code-block:: python
68
69 # Good.
70 import os, sys, time
71 # Good when it does not fit on a single line.
72 import std_lib_module_1, std_lib_module_2, std_lib_module_3
73 import std_lib_module_4, std_lib_module_5, std_lib_module_6
74 # Bad.
75 import os
76 import sys
77 import time
78
79 * Importing class / functions from a module is allowed when these are
80 used multiple times, and no ambiguity is possible.
81
82 .. code-block:: python
83
84 # Good when Bar and Blah are used many times.
85 from foo import Bar, Blah
86 do_something_with(Bar(), Blah(), Bar(), Blah(), Bar(), Blah())
87 # Good in most situations.
88 import foo
89 do_something_with(foo.Bar(), foo.Blah())
90 # Bad.
91 from foo import *
92 from numpy import any # Potential ambiguity with __builtin__.any
93
60 Excerpts 94 Excerpts
61 ~~~~~~~~ 95 ~~~~~~~~
62 96
63 We emphasize here a few important topics that are found in the official 97 We emphasize here a few important topics that are found in the official
64 guidelines: 98 guidelines:
80 verify that something is imported, and avoids duplicated imports. 114 verify that something is imported, and avoids duplicated imports.
81 115
82 * Use absolute imports only. This is compatible across a wider range of 116 * Use absolute imports only. This is compatible across a wider range of
83 Python versions, and avoids confusion about what is being 117 Python versions, and avoids confusion about what is being
84 imported. 118 imported.
119
120 * Avoid renaming imported modules. This makes code more difficult to
121 re-use, and is not grep-friendly.
122
123 .. code-block:: python
124
125 # Good.
126 from theano import tensor
127 # Bad.
128 from theano import tensor as T
85 129
86 * Avoid using lists if all you care about is iterating on something. Using 130 * Avoid using lists if all you care about is iterating on something. Using
87 lists: 131 lists:
88 132
89 - uses more memory (and possibly more CPU if the code may break out of 133 - uses more memory (and possibly more CPU if the code may break out of
175 Additional Recommendations 219 Additional Recommendations
176 -------------------------- 220 --------------------------
177 221
178 Things you should do even if they are not listed in official guidelines: 222 Things you should do even if they are not listed in official guidelines:
179 223
180 * No conditional expression (not supported in Python 2.4). These are 224 * All Python code files should start like this:
181 expressions of the form ``x = y if condition else z``. 225
226 .. code-block:: python
227
228 """Module docstring as the first line, as usual."""
229
230 __authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley"
231 __copyright__ = "(c) 2010, Universite de Montreal"
232 __license__ = "3-clause BSD License"
233 __contact__ = "Name Of Current Guardian of this file <email@address>"
182 234
183 * Use ``//`` for integer division and ``/ float(...)`` if you want the 235 * Use ``//`` for integer division and ``/ float(...)`` if you want the
184 floating point operation (for readability and compatibility across all 236 floating point operation (for readability and compatibility across all
185 versions of Python). 237 versions of Python).
186 238
226 except SomeError: 278 except SomeError:
227 do_something_if_it_failed() 279 do_something_if_it_failed()
228 finally: 280 finally:
229 always_do_this_regardless_of_what_happened() 281 always_do_this_regardless_of_what_happened()
230 282
283 * No conditional expression (not supported in Python 2.4). These are
284 expressions of the form ``x = y if condition else z``.
285
231 * Do not use the ``all`` and ``any`` builtin functions (they are not supported 286 * Do not use the ``all`` and ``any`` builtin functions (they are not supported
232 in Python 2.4). Instead, import them from ``theano.gof.python25`` (or 287 in Python 2.4). Instead, import them from ``theano.gof.python25`` (or
233 use ``numpy.all`` / ``numpy.any`` for array data). 288 use ``numpy.all`` / ``numpy.any`` for array data).
234 289
235 * Do not use the ``hashlib`` module (not supported in Python 2.4). We will 290 * Do not use the ``hashlib`` module (not supported in Python 2.4). We will
236 probably provide a wrapper around it to be compatible with all Python 291 probably provide a wrapper around it to be compatible with all Python
237 versions. 292 versions.
293
294 * Use ``numpy.inf`` and ``numpy.nan`` rather than
295 ``float('inf')`` / ``float('nan')`` (should be slightly more efficient even
296 if efficiency is typically not an issue here, the main goal being code
297 consistency). Also, always use ``numpy.isinf`` / ``numpy.isnan`` to
298 test infinite / NaN values. This is important because ``numpy.nan !=
299 float('nan')``.
238 300
239 * Avoid backslashes whenever possible. They make it more 301 * Avoid backslashes whenever possible. They make it more
240 difficult to edit code, and they are ugly (as well as potentially 302 difficult to edit code, and they are ugly (as well as potentially
241 dangerous if there are trailing white spaces). 303 dangerous if there are trailing white spaces).
242 304
391 453
392 .. code-block:: python 454 .. code-block:: python
393 455
394 import os, sys, time 456 import os, sys, time
395 457
458 Automatic Code Verification
459 ===========================
460
461 Tools will be available to make it easier to automatically ensure that code
462 committed to Pylearn complies to above specifications. This work is not
463 finalized yet, but David started a `Wiki page`_ with helpful configuration
464 tips for Vim.
465
466 .. _Wiki page: http://www.iro.umontreal.ca/~lisa/twiki/bin/view.cgi/Divers/VimPythonRecommendations
467
468 TODO
469 ====
470
471 Things still missing from this document, being discussed in coding_style.txt:
472 - Proper style for C code and Mercurial commits
473 - Enforcing 100% test coverage of the code base
474 - Providing ways to add type checking for function arguments
475