Mercurial > pylearn

annotate doc/v2_planning/coding_style.txt @ 1061:5d96bfef8d6e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged
author Olivier Delalleau <delallea@iro>
date Thu, 09 Sep 2010 13:01:30 -0400
parents b4ccf6b43f27
children 64720cdca3d3
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
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
11 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
12 ----------------------------------------------------------
1017
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
13
1009
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
14 * http://www.python.org/dev/peps/pep-0008/
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
15 * http://www.python.org/dev/peps/pep-0257/
1009
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
16 * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
17 * http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
18 * http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
19 * http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
20 * http://barry.warsaw.us/software/STYLEGUIDE.txt
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
21 * http://self.maluke.com/style
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
22 * http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
23 * http://lists.osafoundation.org/pipermail/dev/2003-March/000479.html
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
24 * http://learnpython.pbworks.com/PythonTricks
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
25 * http://eikke.com/how-not-to-write-python-code/
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
26 * http://jaynes.colorado.edu/PythonGuidelines.html
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
27 * http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
1009
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
28
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
29 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
30 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
31
1050
573363a9b5c7 more tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1049
diff changeset
32 Dumi: we should also try to find tools that automate these
573363a9b5c7 more tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1049
diff changeset
33 processes: pylint, pyflakes, pychecker, pythontidy
1049
ff9361e39c97 remark on fiding tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1033
diff changeset
34
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
35 OD: I think PEP8 + Google guidelines are a good basis.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
36 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
37
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
38 * 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
39 expression, but sometimes using a backslash looks better.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
40 --> 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
41 get rid of them. Typically I prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
42 if (cond_1 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
43 cond_2 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
44 cond_3):
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
45 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
46 if cond_1 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
47 cond_2 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
48 cond_3:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
49
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
50 * 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
51 --> Looks weird to me.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
52
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
53 * Imports should usually be on separate lines
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
54 --> Can be a lot of lines wasted for no obvious benefit. I think this is
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
55 mostly useful when you import different modules from different places,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
56 but I would say that for instance for standard modules it would be
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
57 better to import them all on a single line (doing multiple lines only
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
58 if there are too many of them), e.g. prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
59 import os, sys, time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
60 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
61 import os
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
62 import sys
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
63 import time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
64 However, I agree about separating imports between standard lib / 3rd
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
65 party, e.g. prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
66 import os, sys, time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
67 import numpy, scipy
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
68 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
69 import numpy, os, scipy, sys, time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
70 (Personal note: preferably order imports by alphabetical order, makes
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
71 it easier to quickly see if a specific module is already imported,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
72 and avoids duplicated imports)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
73
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
74 * Missing in PEP 8:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
75 - 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
76 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
77 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
78 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
79 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
80 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
81 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
82 x = my_func(
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
83 a, b, c, d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
84 --> 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
85 few typical examples (and the same happens with multi-lines lists)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
86
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
87 * From PEP 257: The BDFL [3] recommends inserting a blank line between the
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
88 last paragraph in a multi-line docstring and its closing quotes, placing
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
89 the closing quotes on a line by themselves. This way, Emacs'
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
90 fill-paragraph command can be used on it.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
91 --> I have nothing against Emacs, but this is ugly!
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
92
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
93 Documentation
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
94 -------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
95
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
96 How do we write doc?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
97
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
98 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
99 ------------------------------------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
100
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
101 * 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
102
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
103 * 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
104 compatible as possible with Python 3?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
105
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
106 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
107 --------------
1022
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
108
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
109 We also need a c-style coding style.
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
110
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
111 Meetings
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
112 --------
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
113
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
114 * Thursday 2010/09/09, 11 am
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
115