Mercurial > pylearn

annotate doc/v2_planning/coding_style.txt @ 1072:04bbf05d249c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
small comment.
author Frederic Bastien <nouiz@nouiz.org>
date Fri, 10 Sep 2010 10:59:33 -0400
parents 79eb0016f333
children ee7f34fc98fe
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
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
11
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
12
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
13 Fred: This is a refactored thing from James email of what we should put in message
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
14 that we send to the user:
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
15 1) Hint where in the code this log come from.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
16 2) Hint how to hide this message? or we should this into documentation.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
17 3) Tell explicitly if the user can ignore it and the consequence.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
18
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
19 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
20 ----------------------------------------------------------
1017
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
21
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
22 * http://www.python.org/dev/peps/pep-0008/ Style Guide for Python Code
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
23 * http://www.python.org/dev/peps/pep-0257/ Docstring Conventions
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
24 * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html Google Python Style Guide
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
25 * 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
26 * 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
27 * 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
28 * http://barry.warsaw.us/software/STYLEGUIDE.txt
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
29 * http://self.maluke.com/style
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
30 * http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
31 * 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
32 * http://learnpython.pbworks.com/PythonTricks
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
33 * 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
34 * http://jaynes.colorado.edu/PythonGuidelines.html
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
35 * http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
1063
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
36 * http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
1009
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
37
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
38 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
39 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
40
1050
573363a9b5c7 more tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1049
diff changeset
41 Dumi: we should also try to find tools that automate these
573363a9b5c7 more tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1049
diff changeset
42 processes: pylint, pyflakes, pychecker, pythontidy
1049
ff9361e39c97 remark on fiding tools
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1033
diff changeset
43
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
44 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
45
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
46 * 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
47 expression, but sometimes using a backslash looks better.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
48 --> 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
49 get rid of them. Typically I prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
50 if (cond_1 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
51 cond_2 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
52 cond_3):
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
53 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
54 if cond_1 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
55 cond_2 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
56 cond_3:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
57
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
58 * 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
59 --> Looks weird to me.
1063
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
60 (DWF: This is an old convention from the typewriter era. It has more
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
61 or less been wiped out by HTML's convention of ignoring extra
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
62 whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
63 more detail. I think it's okay to drop this convention in source code.)
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
64
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
65 * Imports should usually be on separate lines
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
66 --> 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
67 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
68 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
69 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
70 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
71 import os, sys, time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
72 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
73 import os
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
74 import sys
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
75 import time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
76 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
77 party, e.g. prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
78 import os, sys, time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
79 import numpy, scipy
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
80 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
81 import numpy, os, scipy, sys, time
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
82 (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
83 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
84 and avoids duplicated imports)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
85
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
86 * Missing in PEP 8:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
87 - 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
88 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
89 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
90 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
91 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
92 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
93 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
94 x = my_func(
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
95 a, b, c, d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
96 --> 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
97 few typical examples (and the same happens with multi-lines lists)
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
98 (Fred: I would do 2 or 3, but not 1. I find it more redable when the
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
99 indent is broken after a paranthesis then at any point.
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
100
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
101 * 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
102 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
103 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
104 fill-paragraph command can be used on it.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
105 --> 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
106
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
107 Documentation
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
108 -------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
109
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
110 How do we write doc?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
111
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
112 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
113 ------------------------------------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
114
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
115 * 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
116
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
117 * 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
118 compatible as possible with Python 3?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
119
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
120 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
121 --------------
1022
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
122
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
123 We also need a c-style coding style.
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
124
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
125 Meeting 2010/09/09
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
126 ------------------
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
127
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
128 * Coding guidelines
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
129 PEP 8 & Google should be a good basis to start with.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
130 Task: Highlight the most important points in them (OD).
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
131
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
132 * Documentation
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
133 Use RST with Sphinx.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
134 Task: Provide specific examples on how to document a class, method, and some
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
135 specific classes like Op (DE). Modify the theano documentation to include that.
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
136
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
137 * Python versions to be supported
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
138 Support 2.4 (because some of the clusters are still running 2.4) and write
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
139 code that can be converted to 3.x with 2to3 in a straightforward way.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
140 Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
1063
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
141 (DWF: Pauli Virtanen and others have put together extensive
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
142 documentation in the process of porting NumPy to Py3K, see his notes at
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
143 http://projects.scipy.org/numpy/browser/trunk/doc/Py3K.txt -- this is
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
144 the most complete resource for complicated combinations of Python and C).
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
145
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
146
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
147 * C coding style
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
148 How to write C code (in particular for Numpy / Cuda), and how to mix C and
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
149 Python.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
150 Task: See if there would be a sensible C code style to follow (maybe look how
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
151 Numpy does it), and how projects that mix C and Python deal with it (e.g. use
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
152 separate files, or be able to have mixed syntax highlighting?) (FB)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
153
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
154 * Program output
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
155 Use the warning and logging modules. Avoid print as much as possible.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
156 Task: Look into these modules to define general guidelines e.g. to decide when
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
157 to use warning instead of logging. (DWF)
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
158
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
159 * Automatized code verification
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
160 Use pychecker & friends to make sure everything is fine.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
161 Task: Look into the various options available (DE)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
162
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
163 * Tests
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
164 Force people to write tests. Automatic email reminder of code lines not
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
165 covered by tests (see if we can get this from nosetests). Decorator to mark
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
166 some classes / methods as not being tested yet, so as to be able to
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
167 automatically warn the user when he is using untested stuff (and to remind
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
168 ourselves we should add a test).
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
169 Task: See feasibility. (OD)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
170
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
171 * VIM / Emacs plugins / config files
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
172 To enforce good coding style automatically.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
173 Task: Look for existing options. (FB)
1063
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting.
wardefar@grincheux.iro.umontreal.ca
parents: 1062
diff changeset
174 (DWF: I have put some time into this for vim, I will send around my files)
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
175
1066
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
176 Suggestion by PV
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
177 ----------------
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
178
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
179 Have a sample code that showcases everything one should comply to.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
180
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
181 Some coding guidlines (work-in-progress from OD)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
182 ------------------------------------------------
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
183
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
184 * Avoid using lists if all you care about is iterating on something. Using
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
185 lists:
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
186 - uses more memory (and possibly more CPU if the code may break out of
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
187 the iteration)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
188 - can lead to ugly code when converted to Python 3 with 2to3
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
189 - can have a different behavior if evaluating elements in the list has
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
190 side effects (if you want these side effects, make it explicit by
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
191 assigning the list to some variable before iterating on it)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
192
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
193 Iterative version List version
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
194 my_dict.iterkeys() my_dict.keys()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
195 my_dict.itervalues() my_dict.values()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
196 my_dict.iteritems() my_dict.items()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
197 itertools.imap map
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
198 itertools.ifilter filter
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
199 itertools.izip zip
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
200 xrange range
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
201
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
202 * Use `in` on container objects instead of using class-specific methods.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
203 It is easier to read and may allow you to use your code with different
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
204 container types.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
205
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
206 Yes No
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
207 --- --
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
208 key in my_dict my_dict.has_key(key)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
209 sub_string in my_string my_string.find(sub_string) >= 0
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
210
1070
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
211 * (Point to debate) Avoid contractions in code comments (particularly in
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
212 documentation): "We do not add blue to red because it does not look
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
213 good" rather than "We don't add blue to red because it doesn't look
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
214 good". I mostly find it to be cleaner (been used to it while writing
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
215 scientific articles too).
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
216
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
217 * (Point to debate) Imperative vs. third-person comments. I am used to the
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
218 imperative form and like it better only because it typically saves one
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
219 letter (the 's'): "Return the sum of elements in x" rather than
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
220 "Returns the sum of elements in x".
79eb0016f333 coding_style: Added a couple points to debate
Olivier Delalleau <delallea@iro>
parents: 1067
diff changeset
221