annotate doc/v2_planning/coding_style.txt @ 1229:515033d4d3bf

a first draft of layer committee
author Razvan Pascanu <r.pascanu@gmail.com>
date Wed, 22 Sep 2010 19:43:24 -0400
parents ae4b4f7654ec
children 58a6919d3649
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
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
11 Open for public debate
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
12 ----------------------
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
13
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
14 * File header:
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
15 - Do we put the accents in 'Universite de Montreal'?
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
16 OD: No (restricting code to ASCII characters is much safer)
1181
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
17
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
18 - Do we put the Mercurial version number in each file?
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
19 OD: No (useless in my experience, if it's a release the version
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
20 number can be provided in the README for instance, and in
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
21 addition Mercurial IDs cannot be easily compared to figure
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
22 out which of two versions is most recent)
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
23
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
24 * OD: I like always doing the following when subclassing
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
25 a class A:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
26 class B(A):
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
27 def __init__(self, b_arg_1, b_arg_2, **kw):
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
28 super(B, self).__init__(**kw)
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
29 ...
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
30 The point here is that the constructor always allow for extra keyword
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
31 arguments (except for the class at the very top of the hierarchy), which
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
32 are automatically passed to the parent class.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
33 Pros:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
34 - You do not need to repeat the parent class arguments whenever you
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
35 write a new subclass.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
36 - Whenever you add an argument to the parent class, all child classes
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
37 can benefit from it without modifying their code.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
38 Cons:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
39 - One needs to look at the parent classes to see what these arguments
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
40 are.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
41 - You cannot use a **kw argument in your constructor for your own
1181
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
42 selfish purpose (well, you can actually, but it would look a bit
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
43 hackish).
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
44 - I have no clue whether one could do this with multiple inheritance.
1173
a0f178bc9052 changes during the meeting
pascanur
parents: 1155
diff changeset
45 - Pb if super class adds an argument that has same name as a child class.
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
46 Question: Should we encourage this in Pylearn?
1181
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
47 JB: +0.5
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
48 OD: Was discussed in lab meeting. The feeling was that the last Con was
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
49 too dangerous. Note however that if we have some system that
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
50 automatically generates proper doc (i.e. with all arguments, by
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
51 asking the parent class as well), it could detect the situation
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
52 mentioned in that last Con (and solve the first one as well).
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
53
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
54
1140
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
55 Closed for public debate
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
56 ------------------------
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
57
1181
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
58 * Imperative vs. third-person comments.
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
59 # Return the sum of elements in x. <-- imperative
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
60 # Returns the sum of elements in x. <-- third-person
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
61 OD: I am used to the imperative form and like it better only because it
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
62 typically saves one letter (the 's') and is easier to conjugate.
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
63 JB: What about being compatible with markup formats that have a :returns:
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
64 tag?
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
65 OD: That'd make sense. However, when I wrote the above I hadn't looked
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
66 closely at PEP257 yet, and I just noticed the following official
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
67 recommendation for one-line docstrings in it:
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
68 The docstring is a phrase ending in a period. It prescribes the
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
69 function or method's effect as a command ("Do this", "Return that"), not as a
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
70 description; e.g. don't write "Returns the pathname ...".
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
71 Anyone knows which style is most popular in the open-source
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
72 community?
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
73 OD: In lab meeting Yoshua ruled out: it is a waste of time to even
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
74 discuss it. So we let everyone do it the way they like it best.
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
75
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
76 * Avoid contractions in code comments (particularly in
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
77 documentation): "We do not add blue to red because it does not look good"
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
78 rather than "We don't add blue to red because it doesn't look good".
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
79 OD: I mostly find it to be cleaner (been used to it while writing
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
80 scientific articles too).
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
81 JB: +1
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
82 OD: Discussed in lab meeting, and agreed on.
ae4b4f7654ec coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents: 1179
diff changeset
83
1140
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
84 * Use imports for packages and modules only. I.e. avoid
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
85 from foo import *
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
86 from foo import Bar
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
87 OD: Overall I agree with this. However we probably want to allow some
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
88 exceptions, like:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
89 from itertools import imap, izip
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
90 Also, some people may want to have shortcuts like
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
91 from theano import tensor as T
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
92 but I would prefer to forbid this. It is handy when trying stuff in
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
93 the interactive interpreter, but in real code it can easily get messy
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
94 when you want to copy / paste different pieces of code and they use
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
95 different conventions. Typing tensor.* is a bit longer, but a lot more
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
96 portable.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
97 JB: I thought that these are nice:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
98 - "from foo import Bar"
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
99 - "from foo import Bar, Blah"
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
100 What's wrong with them? They keep the code listing short and readable.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
101 I would discourage these forms when symbols 'Bar' and 'Blah' are
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
102 ambiguous, in which case the parent module prefix serves to disambiguate
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
103 them in the code.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
104 I agree that the "import A as B" form should be discouraged in general,
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
105 because that's just confusing and makes code less grep-friendly.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
106 OD: I agree that "from foo import Bar, Blah" is sometimes convenient
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
107 (typically when you re-use Bar / Blah many times in the same file),
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
108 and would vote in favor of accepting it when it is appropriate.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
109 This guideline was taken from Google's coding recommendation:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
110 "from foo import * or from foo import Bar is very nasty and can
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
111 lead to serious maintenance issues because it makes it hard to find
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
112 module dependencies."
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
113 OD: Decision was taken in committee's meeting to allow
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
114 from foo import Bar, Blah
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
115 when imported stuff is re-used multiple times in the same file, and
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
116 there is no ambiguity.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
117
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
118 * Imports should usually be on separate lines.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
119 OD: I would add an exception, saying it is ok to group multiple imports
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
120 from the standard library on a single line, e.g.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
121 import os, sys, time
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
122 I just don't see much benefit in putting them on separate lines (for
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
123 third-party imports I agree it is best to keep them separate, as it
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
124 makes dependencies clearer, and diffs look better when someone adds /
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
125 removes an import). Does anyone see a good reason to keep standard
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
126 library imports on different lines?
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
127 JB: what does 'usually' mean here? The guideline seems vacuous.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
128 OD: Sorry my fault, I did not quote the whole guideline from PEP8. The
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
129 'usually' was because of what followed:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
130 it's okay to say this though:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
131 from subprocess import Popen, PIPE
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
132 (which btw contradicts Google's recommendation mentioned previously)
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
133 OD: Decision was taken in committee's meeting to allow multiple imports
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
134 on the same line for standard library modules (only).
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
135
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
136 * The BDFL recommends inserting a blank line between the
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
137 last paragraph in a multi-line docstring and its closing quotes, placing
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
138 the closing quotes on a line by themselves. This way, Emacs'
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
139 fill-paragraph command can be used on it.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
140 OD: I think it is ugly and I have not seen it used much. Any Emacs
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
141 user believes it is a must?
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
142 OD: Decision was taken in committee's meeting to drop this
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
143 recommendation.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
144
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
145 * JB: How should we combine capitalization and underscores to name classes
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
146 and functions related to an algorithm like 'SGD' or a model like 'RBM'
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
147 whose common name is capitalized? Case in point: How should I name a
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
148 Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation?
1128
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
149 OD: This one is answered by PEP8 (search HTTPServerError in it).
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
150 You should use:
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
151 RBMClassName
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
152 rbm_function_name
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
153 As far as using abbreviations is concerned:
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
154 All identifiers in the Python standard library (...) SHOULD use
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
155 English words wherever feasible (in many cases, abbreviations and
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
156 technical terms are used which aren't English).
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
157 so I guess HMC is ok when using Hybrid Monte Carlo is considered to
03b41a79bd60 coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents: 1123
diff changeset
158 make some names too long.
1113
60ef81fe1825 2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents: 1103
diff changeset
159
1140
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
160
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
161 Note about warnings
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
162 -------------------
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
163
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
164 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
165 that we send to the user:
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
166 1) Hint where in the code this log come from.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
167 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
168 3) Tell explicitly if the user can ignore it and the consequence.
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
169
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
170 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
171 ----------------------------------------------------------
1017
af80b7d182af coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents: 1009
diff changeset
172
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
173 * Must-read
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
174 * Official Python coding style guide: http://www.python.org/dev/peps/pep-0008
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
175 * Official docstring conventions: http://www.python.org/dev/peps/pep-0257
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
176 * Google Python Style Guide: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
177 * Interesting
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
178 * Code Like a Pythonista: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
1134
0653a85ff2e8 coding_style: Moved url about Numpy conversion to Python 3 to the url list
Olivier Delalleau <delallea@iro>
parents: 1133
diff changeset
179 * Numpy notes on conversion to Python 3: http://projects.scipy.org/numpy/browser/trunk/doc/Py3K.txt
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
180 * Can skip
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
181 * Python style for university class: http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
182 * Mailman coding style: http://barry.warsaw.us/software/STYLEGUIDE.txt
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
183 * Some company coding style: http://self.maluke.com/style
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
184 * Chandler coding style: http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
185 * Outdated recommendations: http://lists.osafoundation.org/pipermail/dev/2003-March/000479.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
186 * Mostly some beginners tips: http://learnpython.pbworks.com/PythonTricks
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
187 * More beginners tips: http://eikke.com/how-not-to-write-python-code/
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
188 * Cogent coding guidelines: http://jaynes.colorado.edu/PythonGuidelines.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
189 * Djangoo coding guidelines: http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
190 * Numpy documentation style guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
191 * Some random guy guidelines (nothing special): http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
1009
dc5185cca21e Added files for Coding Style and Optimization committees
Olivier Delalleau <delallea@iro>
parents:
diff changeset
192
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
193 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
194 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
195
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
196 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
197
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
198 * 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
199 expression, but sometimes using a backslash looks better.
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
200 --> 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
201 get rid of them. Typically I prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
202 if (cond_1 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
203 cond_2 and
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
204 cond_3):
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
205 to
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
206 if cond_1 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
207 cond_2 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
208 cond_3:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
209
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
210 * 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
211 --> 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
212 (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
213 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
214 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
215 more detail. I think it's okay to drop this convention in source code.)
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
216 OD: Cool, thanks, I guess we can drop it then.
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
217
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
218 * Missing in PEP 8:
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
219 - 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
220 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
221 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
222 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
223 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
224 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
225 or
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
226 x = my_func(
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
227 a, b, c, d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
228 --> 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
229 few typical examples (and the same happens with multi-lines lists)
1072
04bbf05d249c small comment.
Frederic Bastien <nouiz@nouiz.org>
parents: 1070
diff changeset
230 (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
231 indent is broken after a paranthesis then at any point.
1075
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
232 OD: After thinking about it, I agreee as well. My recommendation would
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
233 be to go with 2 when it can fit on two lines, and 3 otherwise. Same
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
234 with lists.
1060
b4ccf6b43f27 coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents: 1050
diff changeset
235
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
236 Documentation
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
237 -------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
238
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
239 How do we write doc?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
240
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
241 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
242 ------------------------------------------
1020
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
243
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
244 * 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
245
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
246 * 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
247 compatible as possible with Python 3?
53f6eb80abf1 coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents: 1017
diff changeset
248
1025
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents: 1022
diff changeset
249 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
250 --------------
1022
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
251
e21b3fdec4ef add comments.
Frederic Bastien <nouiz@nouiz.org>
parents: 1020
diff changeset
252 We also need a c-style coding style.
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
253
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
254 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
255 ------------------
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
256
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
257 * Coding guidelines
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
258 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
259 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
260
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
261 * Documentation
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
262 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
263 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
264 specific classes like Op (DE). Modify the theano documentation to include that.
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
265 OD: May want to check out
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
266 http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
267
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
268 * 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
269 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
270 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
271 Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
272
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
273 * C coding style
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
274 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
275 Python.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
276 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
277 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
278 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
279
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
280 * Program output
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
281 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
282 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
283 to use warning instead of logging. (DWF)
1033
f1e0a180574a coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents: 1028
diff changeset
284
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
285 * Automatized code verification
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
286 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
287 Task: Look into the various options available (DE)
1155
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
288 Result: See sections 'Tools to help us out' and 'Automating and enforcing coding
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
289 style'
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
290
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
291 * Tests
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
292 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
293 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
294 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
295 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
296 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
297 Task: See feasibility. (OD)
1132
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
298 Result: See section 'Enforcing strict testing policy'.
1062
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
299
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents: 1060
diff changeset
300 * 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
301 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
302 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
303 (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
304
1066
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
305 Suggestion by PV
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
306 ----------------
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
307
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1062
diff changeset
308 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
309
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1155
diff changeset
310 Fred's suggestion to solve issue with hashlib not available in Python 2.4:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1155
diff changeset
311 --------------------------------------------------------------------------
1073
3e7978201ffc coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents: 1070
diff changeset
312
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1155
diff changeset
313 You can do as in theano.gof.cc:
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
314
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1155
diff changeset
315 ..code::
1133
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions
Olivier Delalleau <delallea@iro>
parents: 1132
diff changeset
316
1136
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
317 if sys.version_info[:2] >= (2,5):
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
318 import hashlib
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
319 def hash_from_code(msg):
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
320 return hashlib.md5(msg).hexdigest()
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
321 else:
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
322 import md5
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
323 def hash_from_code(msg):
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents: 1134
diff changeset
324 return md5.new(msg).hexdigest()
1133
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions
Olivier Delalleau <delallea@iro>
parents: 1132
diff changeset
325
1141
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
326
1075
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
327 Mercurial commits
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
328 -----------------
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
329
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
330 * How to write good commit messages?
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
331 OD: Check Django's guidelines (link above)
1075
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
332 * Standardize the merge commit text (what is the message from fetch?)
d422f726c156 coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents: 1074
diff changeset
333
1141
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
334 During committee's meeting, Fred mentioned a bug with Assembla links for
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
335 multi-line commits.
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
336
1155
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
337 Tools to help us out
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
338 ---------------------
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
339
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
340 Dumi:
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
341
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
342 * pylint: highly configurable and very popular tool, similar in spirit to lint
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
343 for C. Can specify a config file, customize/disable warnings and errors, hook
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
344 it to vim/emacs and include coding style convensions in the check too. A nice
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
345 feature is that you can include a comment like "# pylint: disable-msg=C0103"
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
346 into a file and disable a message locally. This is nice and dangerous at the
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
347 same time. Another cool feature is incremental checking with caching of
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
348 results, which also allows tracking of progress.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
349
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
350 * pyflakes: pylint alternative that is supposedly faster, but is I think more
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
351 limited in the number of things it is good at: "PyFlakes will tell you when
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
352 you have forgotten an import, mistyped a variable name, defined two functions
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
353 with the same name, shadowed a variable from another scope, imported a module
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
354 twice, or two different modules with the same name, and so on.". Most reviews
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
355 found online praise the speed, but note that pylint is clearly superior in
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
356 every other respect.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
357
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
358 * pychecker: it actually *imports* each module (not sure if pylint does this).
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
359 It seems that pylint = pychecker + coding style and that pylint is more
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
360 popular.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
361
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
362 * pep8: if all you care is about obeying PEP-8:
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
363 http://pypi.python.org/pypi/pep8 (includes the actual PEP-8 snippets with the
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
364 errors found, which is neat). Otherwise, pylint seems like a superset of this.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
365
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
366 * http://www.doughellmann.com/articles/pythonmagazine/completely-different/2008-03-linters/index.html
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
367 - article from 2008 comparing pylint, pychecker, and pyflakes. The conclusion
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
368 is to use pylint, more or less.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
369
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
370 I say we stick with pylint for now as it provides a great degree of flexibility
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
371 in a single mature package.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
372
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
373 * vim + pylint: http://www.vim.org/scripts/script.php?script_id=891
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
374 * emcas + pylint: http://www.emacswiki.org/emacs/PythonProgrammingInEmacs#toc5
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
375
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
376 Automating and enforcing coding style
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
377 -------------------------------------
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
378
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
379 Ideally, we would like to have a uniform approach to this, where everyone tests
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
380 against the same tool(s) and uses the same list of disabled warnings etc.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
381
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
382 Dumi: there are several ways of approaching this, independently of the tools used:
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
383
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
384 * Create a precommit hook for mercurial, which runs the tool(s) of choice and
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
385 generates warnings or aborts the commit process. This hook is a simple Python
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
386 module (well, as simple as we want it to be), which we can include into
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
387 everyone's hgrc, in the precommit.pylint variable, for instance. An example
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
388 is http://github.com/jrburke/dvcs_jslint/blob/master/dvcs_jslint.js. The
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
389 advantage of this approach is that the load is distributed and
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
390 errors/warnings are caught client-side, before the commit.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
391
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
392 * Another client-side option is to have editor plugins for the various style
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
393 checkers: vim and emacs can access pylint pretty easily for instance.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
394
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
395 * Instead of doing this client-side, one can do things server-side. On
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
396 Assembla, this means using their Webhooks
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
397 (http://www.assembla.com/spaces/demostuff/webhook_tool), since HTTP-based
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
398 hooks that we would need to tie with our buildbot server (whichever server we
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
399 choose that to be).
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
400
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
401 * I (DE) prefer starting with the client-side approach, as it is easier to
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
402 implement, has no single point of failure and is deployable fast. We could
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
403 have a "batch" script that runs our lint tools in conjunction with hg
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
404 annotate and sends hate-mail once a week to offenders who have somehow
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
405 slipped things through the cracks. Also on the server-side we could run
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
406 time-consuming checking (though how such checks would differ from tests is
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
407 unclear).
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
408
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
409 Note that:
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
410
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
411 * I haven't found anything ready-made online, so we need to write these
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
412 hooks ourselves.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
413 * I think we should make it so that it is not possible to commit things if
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
414 pylint reports an actual error.
b70a1fcb7b4f coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents: 1152
diff changeset
415
1123
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
416 Type checking
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
417 -------------
1103
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section
Olivier Delalleau <delallea@iro>
parents: 1075
diff changeset
418
1123
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
419 (Suggested by Francois Savard)
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
420
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
421 vu que vous êtes en train de vous occuper de l'aspect coding style, je
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
422 mentionne ceci, à faire ce que vous en voulez: j'aime bien éviter des
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
423 erreurs sur l'ordre de mes paramètres, sur les assumptions sur les
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
424 paramètres etc. en faisant des argument check. Ça remplace un peu le
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
425 static type checking des langages genre Java.
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
426
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
427 En Python y'a une façon élégante de définir ses propres typecheckers,
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
428 value checkers etc. et ensuite les passer en paramètre à un décorateur de
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
429 fonction:
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
430
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
431 http://code.activestate.com/recipes/454322-type-checking-decorator/
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
432
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
433 (Juste un exemple, vu que les checks peuvent être plus élaborés, inclure
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
434 des value checks (>0 etc.), être flexibles pour ne pas demander que ce
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
435 soit un type fixe mais plutôt que ça réponde à certaines contraintes (que
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
436 ça "ressemble" à un float, p. ex.). J'avais développé une lib pour faire
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
437 qqch du genre en Javascript).
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
438
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
439 Je ne sais pas si vous comptiez parler de ça, et si ça vaut la peine, mais
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
440 personnellement je préfère du code à des commentaires qui peuvent être out
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
441 of sync avec le contenu d'une méthode. Si vous croyez que ça vaut la peine,
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
442 vous pourriez p-e définir des type/value-checkers standards pour éviter que
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
443 tout le monde redéfinissent les siens à sa façon.
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents: 1113
diff changeset
444
1141
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
445 OD: This was discussed in committee's meeting. We agreed to provide ways to do
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
446 this, but not to enforce its usage.
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
447
1132
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
448 Enforcing strict testing policy
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
449 -------------------------------
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
450
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
451 The `coverage` third-party module provides a way to gather code coverage
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
452 statistics in the test suite. `nosetests` has a plugin that can be activated
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
453 with the --with-coverage option to use this module.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
454 It is possible to know which lines specifically lack coverage. However, we
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
455 will probably want to post-process this data to do more than a simple report
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
456 (which noone will care about). This could be done either by parsing nosetests'
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
457 coverage output, or modifying its coverage plugin, or writing our own version
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
458 of it. The main goal would be to identify who is responsible for writing lines
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
459 that are not currently covered (using 'hg annotate'), in order to send email
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
460 notifications.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
461
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
462 We should aim at 100% code coverage in tests. This is realistic because
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
463 `coverage` offers ways to ignore coverage for lines we explicitely do not want
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
464 to cover (typically debug code, or AssertionError / NotImplementedError that
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
465 are not supposed to be triggered during normal usage).
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
466 We may need to do some advanced processing though to e.g. collect results from
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
467 multiple build bots, if for instance some bot is running tests without GPU
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
468 support, and another one is taking care of the GPU tests.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
469
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
470 Code that should be tested but for which no test is currently written would
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
471 also require some decorator / helper function that would trigger a warning at
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
472 run-time (only once / execution). This could be enforced by adopting a
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
473 different policy about lack-of-coverage notification emails, depending on
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
474 whether or not the warning is present:
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
475 - if there is no warning, daily email notification (ADD A WARNING!!!)
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
476 - if there is a warning, weekly email notification (ADD A TEST!!!)
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents: 1130
diff changeset
477
1140
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
478 Meeting 2010/09/16
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
479 ------------------
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
480
1141
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
481 Tasks to be performed by tomorrow:
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
482 * OD:
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
483 * Write down summary of Python coding style recommendations
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
484 * Start a file that showcases those guidelines
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
485 * DWF:
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
486 * Look into recommendations on how to document a class, method, ...
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
487 * Write recommendations on when to use logging vs. warning
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
488 * Make public some configuration files / plugins for vim
6c79394b6b20 coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents: 1140
diff changeset
489 * Come up with official common file header (license in particular)
1140
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents: 1138
diff changeset
490
1170
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
491 Script usage documentation
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
492 --------------------------
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
493
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
494 OD: It would be nice to have some standardized way of parsing a script's
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
495 arguments and displaying the script usage doc to the user.
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
496
1178
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents: 1170
diff changeset
497 Recommendations for serialization
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents: 1170
diff changeset
498 ---------------------------------
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents: 1170
diff changeset
499
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents: 1170
diff changeset
500 We need to add coding style guidelines to make sure code is properly
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents: 1170
diff changeset
501 serializable.
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents: 1170
diff changeset
502