Mercurial > pylearn

comparison doc/v2_planning/API_coding_style.txt @ 1145:d6d73a9f07b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
API_coding_style: Started to work on official guidelines
author Olivier Delalleau <delallea@iro>
date Thu, 16 Sep 2010 16:11:26 -0400
parents fa1715e759e3
children f6011a2aff0b
comparison
equal deleted inserted replaced
1143:fa1715e759e3 1145:d6d73a9f07b8
1 ========================= 1 =========================
2 Coding Style Guidelines 2 Coding Style Guidelines
3 ========================= 3 =========================
4
5 Main Goals
6 ==========
7
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
10 for code dependent on Theano.
11
12 * Code should be easy to read, understand and update by developers and
13 users.
14
15 * Code should be well-documented and well-tested.
4 16
5 Code Sample 17 Code Sample
6 =========== 18 ===========
7 19
8 The following code sample illustrates many of the coding guidelines one should 20 The following code sample illustrates many of the coding guidelines one should
10 22
11 .. code-block:: python 23 .. code-block:: python
12 24
13 import os, sys, time 25 import os, sys, time
14 26
27 Python Coding Guidelines
28 ========================
15 29
30 Official Guidelines
31 -------------------
32
33 Source Material
34 ~~~~~~~~~~~~~~~
35
36 The three main documents describing our Python coding guidelines are:
37 * `PEP 8 -- Style Guide for Python Code
38 <http://www.python.org/dev/peps/pep-0008>`_
39 * `PEP 257 -- Docstring Conventions
40 <http://www.python.org/dev/peps/pep-0257>`_
41 * `Google Python Style Guide
42 <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_
43
44 However, there are a few points mentioned in those documents that we decided
45 to do differently:
46
47 * Use only one space (not two) after a sentence-ending period in comments.
48
49 Excerpts
50 ~~~~~~~~
51
52 We emphasize here a few important topics that are found in the official
53 guidelines:
54
55 Additional Recommendations
56 --------------------------
57
58 Things you should do even if they are not listed in official guidelines:
59
60 * Avoid backslashes whenever possible. They make it more
61 difficult to edit code, and they are ugly (as well as potentially
62 dangerous if there are trailing white spaces).
63
64 .. code-block:: python
65
66 # Good.
67 if (cond_1 and
68 cond_2 and
69 cond_3):
70 ...
71 # Bad.
72 if cond_1 and \
73 cond_2 and \
74 cond_3:
75 ...
76
77 * When indenting multi-line statements like lists or function arguments,
78 keep elements of the same level aligned with each other.
79 The position of the first
80 element (on the same line or a new line) should be chosen depending on
81 what is easiest to read (sometimes both can be ok).
82
83 .. code-block:: python
84
85 # Good.
86 for my_very_long_variable_name in [my_food, my_bar, my_love,
87 my_everything]:
88 ...
89 for my_very_long_variable_name in [
90 my_foo, my_bar, my_love, my_everything]:
91 ...
92 # Good iff the list needs to be frequently updated.
93 for my_very_long_variable_name in [
94 my_foo,
95 my_bar,
96 my_love,
97 my_everything,
98 ]:
99 ...
100 # Bad.
101 for my_very_long_variable_name in [my_foo, my_bar, my_love,
102 my_everything]:
103 ...
104 for my_very_long_variable_name in [my_foo,
105 my_bar,
106 my_love,
107 my_everything]:
108 ...
109