Mercurial > pylearn

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