Mercurial > pylearn
annotate doc/v2_planning/coding_style.txt @ 1526:5804e44d7a1b
pep8
| author | Frederic Bastien <nouiz@nouiz.org> |
|---|---|
| date | Fri, 09 Nov 2012 16:58:17 -0500 |
| parents | 7185d194bb7e |
| children |
| 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 | 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 |
| 1313 | 25 |
| 26 .. code-block:: python | |
| 27 | |
|
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
|
28 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
|
29 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
|
30 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
|
31 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
|
32 ... |
| 1313 | 33 |
|
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
|
34 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
|
35 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
|
36 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
|
37 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
|
38 - 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
|
39 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
|
40 - 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
|
41 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
|
42 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
|
43 - 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
|
44 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
|
45 - 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
|
46 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
|
47 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
|
48 - I have no clue whether one could do this with multiple inheritance. |
| 1173 | 49 - 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
|
50 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
|
51 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
|
52 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
|
53 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
|
54 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
|
55 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
|
56 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
|
57 |
|
1113
60ef81fe1825
2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents:
1103
diff
changeset
|
58 |
|
1140
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
59 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
|
60 ------------------------ |
|
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
61 |
|
1181
ae4b4f7654ec
coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents:
1179
diff
changeset
|
62 * 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
|
63 # 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
|
64 # 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
|
65 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
|
66 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
|
67 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
|
68 tag? |
|
ae4b4f7654ec
coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents:
1179
diff
changeset
|
69 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
|
70 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
|
71 recommendation for one-line docstrings in it: |
| 1313 | 72 |
| 73 The docstring is a phrase ending in a period. It prescribes the | |
| 74 function or method's effect as a command ("Do this", "Return that"), not as a | |
| 75 description; e.g. don't write "Returns the pathname ...". | |
| 76 | |
|
1181
ae4b4f7654ec
coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents:
1179
diff
changeset
|
77 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
|
78 community? |
|
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: 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
|
80 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
|
81 |
|
ae4b4f7654ec
coding_style: Updated / closed some points open for debate that were discussed during meeting
Olivier Delalleau <delallea@iro>
parents:
1179
diff
changeset
|
82 * 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
|
83 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
|
84 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
|
85 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
|
86 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
|
87 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
|
88 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
|
89 |
|
1140
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
90 * 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
|
91 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
|
92 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
|
93 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
|
94 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
|
95 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
|
96 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
|
97 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
|
98 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
|
99 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
|
100 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
|
101 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
|
102 portable. |
|
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
103 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
|
104 - "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
|
105 - "from foo import Bar, Blah" |
| 1313 | 106 |
|
1140
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
107 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
|
108 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
|
109 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
|
110 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
|
111 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
|
112 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
|
113 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
|
114 (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
|
115 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
|
116 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
|
117 "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
|
118 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
|
119 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
|
120 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
|
121 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
|
122 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
|
123 there is no ambiguity. |
|
1293
879a5633bb52
A small addendum about the 'import A as B' moratorium.
David Warde-Farley <wardefar@iro.umontreal.ca>
parents:
1255
diff
changeset
|
124 DWF: One exception I'd like to propose to the "import A as B" moratorium |
|
879a5633bb52
A small addendum about the 'import A as B' moratorium.
David Warde-Farley <wardefar@iro.umontreal.ca>
parents:
1255
diff
changeset
|
125 is that we adopt the "import numpy as np" standard that's used in |
|
879a5633bb52
A small addendum about the 'import A as B' moratorium.
David Warde-Farley <wardefar@iro.umontreal.ca>
parents:
1255
diff
changeset
|
126 NumPy and SciPy itself. For NumPy heavy code this really cuts down |
|
879a5633bb52
A small addendum about the 'import A as B' moratorium.
David Warde-Farley <wardefar@iro.umontreal.ca>
parents:
1255
diff
changeset
|
127 on clutter, without significant impact on readability (IMHO). |
|
1306
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
128 OD: We discussed it during a meeting. We agreed not to use the 'np' |
|
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
129 abbreviation at first. We may still revisit this point in the future |
|
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
130 if we find situations where it would really help. |
|
1140
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
131 |
|
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
132 * 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
|
133 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
|
134 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
|
135 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
|
136 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
|
137 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
|
138 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
|
139 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
|
140 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
|
141 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
|
142 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
|
143 '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
|
144 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
|
145 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
|
146 (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
|
147 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
|
148 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
|
149 |
|
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
150 * 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
|
151 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
|
152 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
|
153 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
|
154 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
|
155 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
|
156 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
|
157 recommendation. |
|
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
158 |
|
1113
60ef81fe1825
2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents:
1103
diff
changeset
|
159 * 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
|
160 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
|
161 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
|
162 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
|
163 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
|
164 You should use: |
|
03b41a79bd60
coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents:
1123
diff
changeset
|
165 RBMClassName |
|
03b41a79bd60
coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents:
1123
diff
changeset
|
166 rbm_function_name |
|
03b41a79bd60
coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents:
1123
diff
changeset
|
167 As far as using abbreviations is concerned: |
|
03b41a79bd60
coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents:
1123
diff
changeset
|
168 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
|
169 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
|
170 technical terms are used which aren't English). |
|
03b41a79bd60
coding_style: Replies to James' questions / comments
Olivier Delalleau <delallea@iro>
parents:
1123
diff
changeset
|
171 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
|
172 make some names too long. |
|
1113
60ef81fe1825
2cents in coding_style
James Bergstra <bergstrj@iro.umontreal.ca>
parents:
1103
diff
changeset
|
173 |
|
1140
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
174 |
|
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
|
175 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
|
176 ------------------- |
| 1072 | 177 |
| 178 Fred: This is a refactored thing from James email of what we should put in message | |
| 179 that we send to the user: | |
| 180 1) Hint where in the code this log come from. | |
| 181 2) Hint how to hide this message? or we should this into documentation. | |
| 182 3) Tell explicitly if the user can ignore it and the consequence. | |
| 183 | |
|
1025
1c96e7ad95c3
coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents:
1022
diff
changeset
|
184 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
|
185 ---------------------------------------------------------- |
|
1017
af80b7d182af
coding_style: Added list of participants in the committee
Olivier Delalleau <delallea@iro>
parents:
1009
diff
changeset
|
186 |
|
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
|
187 * 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
|
188 * 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
|
189 * 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
|
190 * 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
|
191 * 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
|
192 * 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
|
193 * 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
|
194 * 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
|
195 * 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
|
196 * 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
|
197 * 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
|
198 * 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
|
199 * 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
|
200 * 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
|
201 * 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
|
202 * 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
|
203 * 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
|
204 * 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
|
205 * 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
|
206 |
|
1020
53f6eb80abf1
coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents:
1017
diff
changeset
|
207 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
|
208 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
|
209 |
|
1060
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
210 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
|
211 |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
212 * 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
|
213 expression, but sometimes using a backslash looks better. |
| 1313 | 214 --> I rarely find that backslash looks better. In most situations you can |
| 215 get rid of them. Typically I prefer: | |
| 216 | |
| 217 ..code-block:: python | |
| 218 | |
|
1060
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
219 if (cond_1 and |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
220 cond_2 and |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
221 cond_3): |
| 1313 | 222 |
| 223 to | |
| 224 | |
| 225 ..code-block:: python | |
| 226 | |
|
1060
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
227 if cond_1 and \ |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
228 cond_2 and \ |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
229 cond_3: |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
230 |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
231 * You should use two spaces after a sentence-ending period. |
| 1313 | 232 --> Looks weird to me. |
| 233 (DWF: This is an old convention from the typewriter era. It has more | |
| 234 or less been wiped out by HTML's convention of ignoring extra | |
| 235 whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for | |
| 236 more detail. I think it's okay to drop this convention in source code.) | |
| 237 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
|
238 |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
239 * Missing in PEP 8: |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
240 - 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
|
241 x = my_func(a, b, c, |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
242 d, e, f) |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
243 or |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
244 x = my_func(a, b, c, |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
245 d, e, f) |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
246 or |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
247 x = my_func( |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
248 a, b, c, d, e, f) |
|
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
249 --> 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
|
250 few typical examples (and the same happens with multi-lines lists) |
| 1072 | 251 (Fred: I would do 2 or 3, but not 1. I find it more redable when the |
| 252 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
|
253 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
|
254 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
|
255 with lists. |
|
1060
b4ccf6b43f27
coding_style: Added some comments about PEP8
Olivier Delalleau <delallea@iro>
parents:
1050
diff
changeset
|
256 |
|
1025
1c96e7ad95c3
coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents:
1022
diff
changeset
|
257 Documentation |
|
1c96e7ad95c3
coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents:
1022
diff
changeset
|
258 ------------- |
|
1020
53f6eb80abf1
coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents:
1017
diff
changeset
|
259 |
| 1298 | 260 How do we write docs? |
| 261 | |
| 262 Ideas (DE): | |
| 263 | |
| 264 * Most major Python projects suggest following PEP-257: | |
|
1300
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
265 http://www.python.org/dev/peps/pep-0257/, which contains conventions on |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
266 writing docstrings (what they should contain, not the specific markup) |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
267 for Python. These are very general conventions, however,. |
| 1298 | 268 |
| 269 * Numpy, in particular, has a very nice page on how to document things if | |
|
1300
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
270 contributing: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
271 (it's mostly about documentation, not coding style, despite the page |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
272 name). |
| 1298 | 273 |
|
1300
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
274 * A pretty good example from numpy, with relevant comments: |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
275 http://github.com/numpy/numpy/blob/master/doc/example.py |
| 1298 | 276 |
| 277 * A real-life example (record arrays) from numpy: | |
|
1300
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
278 http://github.com/numpy/numpy/blob/master/numpy/core/records.py |
| 1298 | 279 |
| 280 * The recommendations are quite sane and common-sense, we should follow them. | |
|
1300
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
281 |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
282 * numpy's way of doing things is a bit different from the way we currently |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
283 document Theano: they don't use param/type/rtype, for instance, but nice |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
284 readable section titles. I personally find their approach better-looking |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
285 and they do have a sphinx extension that would allow us to have the same |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
286 style |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
287 (http://github.com/numpy/numpy/blob/master/doc/sphinxext/numpydoc.py). |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
288 The disadvantage of taking this approach is that Theano and Pylearn will |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
289 be documented slightly differently |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
290 |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
291 * Make sure that what we write is compatible with tools like sphinx's |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
292 autodoc extension: |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
293 http://sphinx.pocoo.org/ext/autodoc.html#module-sphinx.ext.autodoc (which |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
294 we will most probably use to generate semi-automatic pretty docs) |
| 1298 | 295 |
| 296 * Nice cheat-sheet for docutils: | |
|
1300
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
297 http://docutils.sourceforge.net/docs/user/rst/quickref.html |
| 1298 | 298 |
| 299 * http://docs.python.org/release/2.5.2/lib/module-doctest.html - | |
|
1300
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
300 in-documentation unit-testing: we should perhaps encourage people to |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
301 write such things where warranted (where there are interesting usage |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
302 examples). notetests can automatically run those, so no configuration |
|
cc1c5720eeca
clarifications on sphinx default vs. numpydoc extension
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1299
diff
changeset
|
303 overhead is necessary. |
|
1020
53f6eb80abf1
coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents:
1017
diff
changeset
|
304 |
|
1025
1c96e7ad95c3
coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents:
1022
diff
changeset
|
305 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
|
306 ------------------------------------------ |
|
1020
53f6eb80abf1
coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents:
1017
diff
changeset
|
307 |
|
1025
1c96e7ad95c3
coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents:
1022
diff
changeset
|
308 * 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
|
309 |
|
1c96e7ad95c3
coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents:
1022
diff
changeset
|
310 * Is it reasonable to have coding guidelines that would make the code as |
| 1313 | 311 compatible as possible with Python 3? |
|
1020
53f6eb80abf1
coding_style: More links and sections to discuss
Olivier Delalleau <delallea@iro>
parents:
1017
diff
changeset
|
312 |
|
1025
1c96e7ad95c3
coding_style: Added discussion point about backward compatibility with Python 2.x versions
Olivier Delalleau <delallea@iro>
parents:
1022
diff
changeset
|
313 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
|
314 -------------- |
| 1022 | 315 |
| 316 We also need a c-style coding style. | |
|
1033
f1e0a180574a
coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents:
1028
diff
changeset
|
317 |
|
1062
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
318 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
|
319 ------------------ |
|
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
320 |
|
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
321 * Coding guidelines |
| 1313 | 322 PEP 8 & Google should be a good basis to start with. |
| 323 Task: Highlight the most important points in them (OD). | |
|
1062
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
324 |
|
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
325 * Documentation |
| 1313 | 326 Use RST with Sphinx. |
| 327 Task: Provide specific examples on how to document a class, method, and some | |
| 328 specific classes like Op (DE). Modify the theano documentation to include that. | |
| 329 OD: May want to check out | |
| 330 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
|
331 |
|
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
332 * Python versions to be supported |
| 1313 | 333 Support 2.4 (because some of the clusters are still running 2.4) and write |
| 334 code that can be converted to 3.x with 2to3 in a straightforward way. | |
| 335 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
|
336 |
|
1062
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
337 * C coding style |
| 1313 | 338 How to write C code (in particular for Numpy / Cuda), and how to mix C and |
| 339 Python. | |
| 340 Task: See if there would be a sensible C code style to follow (maybe look how | |
| 341 Numpy does it), and how projects that mix C and Python deal with it (e.g. use | |
| 342 separate files, or be able to have mixed syntax highlighting?) (FB) | |
|
1062
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
343 |
|
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
344 * Program output |
| 1313 | 345 Use the warning and logging modules. Avoid print as much as possible. |
| 346 Task: Look into these modules to define general guidelines e.g. to decide when | |
| 347 to use warning instead of logging. (DWF) | |
|
1033
f1e0a180574a
coding_style: Added meeting date & time
Olivier Delalleau <delallea@iro>
parents:
1028
diff
changeset
|
348 |
|
1062
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
349 * Automatized code verification |
| 1313 | 350 Use pychecker & friends to make sure everything is fine. |
| 351 Task: Look into the various options available (DE) | |
| 352 Result: See sections 'Tools to help us out' and 'Automating and enforcing coding | |
| 353 style' | |
|
1062
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
354 |
|
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
355 * Tests |
| 1313 | 356 Force people to write tests. Automatic email reminder of code lines not |
| 357 covered by tests (see if we can get this from nosetests). Decorator to mark | |
| 358 some classes / methods as not being tested yet, so as to be able to | |
| 359 automatically warn the user when he is using untested stuff (and to remind | |
| 360 ourselves we should add a test). | |
| 361 Task: See feasibility. (OD) | |
| 362 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
|
363 |
|
64720cdca3d3
coding_style: Notes from today's meeting and tasks for next week
Olivier Delalleau <delallea@iro>
parents:
1060
diff
changeset
|
364 * VIM / Emacs plugins / config files |
| 1313 | 365 To enforce good coding style automatically. |
| 366 Task: Look for existing options. (FB) | |
| 367 (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
|
368 |
|
1066
e1aca94f28d8
coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents:
1062
diff
changeset
|
369 Suggestion by PV |
|
e1aca94f28d8
coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents:
1062
diff
changeset
|
370 ---------------- |
|
e1aca94f28d8
coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents:
1062
diff
changeset
|
371 |
|
e1aca94f28d8
coding_style: Added suggestion from PV, and a few coding guidelines
Olivier Delalleau <delallea@iro>
parents:
1062
diff
changeset
|
372 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
|
373 |
|
1159
531e77fb67f2
coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents:
1155
diff
changeset
|
374 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
|
375 -------------------------------------------------------------------------- |
|
1073
3e7978201ffc
coding_style: Some more python coding guidelines
Olivier Delalleau <delallea@iro>
parents:
1070
diff
changeset
|
376 |
|
1159
531e77fb67f2
coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents:
1155
diff
changeset
|
377 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
|
378 |
|
1159
531e77fb67f2
coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents:
1155
diff
changeset
|
379 ..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
|
380 |
|
1136
5f0c8ff2b3b6
tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents:
1134
diff
changeset
|
381 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
|
382 import hashlib |
|
5f0c8ff2b3b6
tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents:
1134
diff
changeset
|
383 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
|
384 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
|
385 else: |
|
5f0c8ff2b3b6
tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents:
1134
diff
changeset
|
386 import md5 |
|
5f0c8ff2b3b6
tell how do to some stuff to be compatible with python2.4
Frederic Bastien <nouiz@nouiz.org>
parents:
1134
diff
changeset
|
387 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
|
388 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
|
389 |
|
1141
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
390 |
|
1075
d422f726c156
coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents:
1074
diff
changeset
|
391 Mercurial commits |
|
d422f726c156
coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents:
1074
diff
changeset
|
392 ----------------- |
|
d422f726c156
coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents:
1074
diff
changeset
|
393 |
|
d422f726c156
coding_style: Discussion and one more point to think about
Olivier Delalleau <delallea@iro>
parents:
1074
diff
changeset
|
394 * 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
|
395 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
|
396 * 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
|
397 |
|
1141
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
398 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
|
399 multi-line commits. |
|
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
400 |
|
1306
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
401 OD: About what I mentioned in a meeting: |
|
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
402 - The size of the first line does not really matter (although keeping it |
|
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
403 short is better, it is not truncated when you do 'hg log') |
|
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
404 - The fetch commit message is like "Automated merge with |
|
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
405 https://theanoclone.googlecode.com/hg/". It is too long to ask people to |
|
ef0f3deead94
coding_style: Updates about a few points discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1304
diff
changeset
|
406 use the same. I guess "Merge" would be the most logical message to use. |
|
1311
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
407 |
|
1316
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
408 FB: The proposed guidelines |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
409 * A one line summary. Try to keep it short, and provide the information |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
410 that seems most useful to other developers: in particular the goal of |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
411 a change is more useful than its description (which is always |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
412 available through the changeset patch log). E.g. say "Improved stability |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
413 of cost computation" rather than "Replaced log(exp(a) + exp(b)) by |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
414 a * log(1 + exp(b -a)) in cost computation". |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
415 * If needed a blank line followed by a more detailed summary |
|
1311
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
416 * Make a commit for each logical modification |
|
1316
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
417 * This makes reviews easier to do |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
418 * This makes debugging easier as we can more easily pinpoint errors in commits with hg bisect |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
419 * NEVER commit reformatting with functionality changes |
|
1311
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
420 * HG RECORD/DIFF are your friend |
|
1316
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
421 * hg record allows you to select which changes to a file should be |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
422 committed |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
423 * hg record / diff force you to review your code, never commit without |
|
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
424 running one of these two commands first |
|
1311
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
425 * Stuff from django guide |
|
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
426 * Write detailed commit messages in the past tense, not present tense. |
|
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
427 * Good: "Fixed Unicode bug in RSS API." |
|
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
428 * Bad: "Fixes Unicode bug in RSS API." |
|
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
429 * Bad: "Fixing Unicode bug in RSS API." |
|
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
430 * Separate bug fixes from feature changes. |
|
1316
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
431 * If fix a ticket, make the message start with "Fixed #abc" |
|
1311
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
432 * Can make a system to change the ticket? |
|
1316
3234913a3642
Fixed some typos and added a few precisions in commit message guidelines
Olivier Delalleau <delallea@iro>
parents:
1313
diff
changeset
|
433 * If reference a ticket, make the message start with "Refs #abc" |
|
1311
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
434 * Can make a system to put a comment to the ticket? |
|
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
435 |
|
431d0db69499
added info about the commit message.
Frederic Bastien <nouiz@nouiz.org>
parents:
1306
diff
changeset
|
436 |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
437 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
|
438 --------------------- |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
439 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
440 Dumi: |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
441 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
442 * pylint: highly configurable and very popular tool, similar in spirit to lint |
| 1313 | 443 for C. Can specify a config file, customize/disable warnings and errors, hook |
| 444 it to vim/emacs and include coding style convensions in the check too. A nice | |
| 445 feature is that you can include a comment like "# pylint: disable-msg=C0103" | |
| 446 into a file and disable a message locally. This is nice and dangerous at the | |
| 447 same time. Another cool feature is incremental checking with caching of | |
| 448 results, which also allows tracking of progress. | |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
449 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
450 * pyflakes: pylint alternative that is supposedly faster, but is I think more |
| 1313 | 451 limited in the number of things it is good at: "PyFlakes will tell you when |
| 452 you have forgotten an import, mistyped a variable name, defined two functions | |
| 453 with the same name, shadowed a variable from another scope, imported a module | |
| 454 twice, or two different modules with the same name, and so on.". Most reviews | |
| 455 found online praise the speed, but note that pylint is clearly superior in | |
| 456 every other respect. | |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
457 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
458 * pychecker: it actually *imports* each module (not sure if pylint does this). |
| 1313 | 459 It seems that pylint = pychecker + coding style and that pylint is more |
| 460 popular. | |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
461 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
462 * pep8: if all you care is about obeying PEP-8: |
| 1313 | 463 http://pypi.python.org/pypi/pep8 (includes the actual PEP-8 snippets with the |
| 464 errors found, which is neat). Otherwise, pylint seems like a superset of this. | |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
465 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
466 * 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
|
467 - 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
|
468 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
|
469 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
470 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
|
471 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
|
472 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
473 * 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
|
474 * 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
|
475 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
476 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
|
477 ------------------------------------- |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
478 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
479 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
|
480 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
|
481 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
482 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
|
483 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
484 * Create a precommit hook for mercurial, which runs the tool(s) of choice and |
| 1313 | 485 generates warnings or aborts the commit process. This hook is a simple Python |
| 486 module (well, as simple as we want it to be), which we can include into | |
| 487 everyone's hgrc, in the precommit.pylint variable, for instance. An example | |
| 488 is http://github.com/jrburke/dvcs_jslint/blob/master/dvcs_jslint.js. The | |
| 489 advantage of this approach is that the load is distributed and | |
| 490 errors/warnings are caught client-side, before the commit. | |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
491 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
492 * Another client-side option is to have editor plugins for the various style |
| 1313 | 493 checkers: vim and emacs can access pylint pretty easily for instance. |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
494 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
495 * Instead of doing this client-side, one can do things server-side. On |
| 1313 | 496 Assembla, this means using their Webhooks |
| 497 (http://www.assembla.com/spaces/demostuff/webhook_tool), since HTTP-based | |
| 498 hooks that we would need to tie with our buildbot server (whichever server we | |
| 499 choose that to be). | |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
500 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
501 * I (DE) prefer starting with the client-side approach, as it is easier to |
| 1313 | 502 implement, has no single point of failure and is deployable fast. We could |
| 503 have a "batch" script that runs our lint tools in conjunction with hg | |
| 504 annotate and sends hate-mail once a week to offenders who have somehow | |
| 505 slipped things through the cracks. Also on the server-side we could run | |
| 506 time-consuming checking (though how such checks would differ from tests is | |
| 507 unclear). | |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
508 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
509 Note that: |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
510 |
|
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
511 * I haven't found anything ready-made online, so we need to write these |
| 1313 | 512 hooks ourselves. |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
513 * I think we should make it so that it is not possible to commit things if |
| 1313 | 514 pylint reports an actual error. |
|
1155
b70a1fcb7b4f
coding_style: tools to make life easier and automating certain processes
Dumitru Erhan <dumitru.erhan@gmail.com>
parents:
1152
diff
changeset
|
515 |
|
1123
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
516 Type checking |
|
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
517 ------------- |
|
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
|
518 |
|
1123
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
519 (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
|
520 |
|
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
521 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
|
522 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
|
523 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
|
524 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
|
525 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
|
526 |
|
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
527 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
|
528 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
|
529 fonction: |
|
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
530 |
|
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
531 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
|
532 |
|
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
533 (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
|
534 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
|
535 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
|
536 ç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
|
537 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
|
538 |
|
1a1c0c3adcca
coding_style: Added suggestion made by email by Francois about type checking
Olivier Delalleau <delallea@iro>
parents:
1113
diff
changeset
|
539 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
|
540 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
|
541 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
|
542 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
|
543 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
|
544 |
|
1141
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
545 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
|
546 this, but not to enforce its usage. |
|
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
547 |
|
1132
f0a1b88367b0
coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents:
1130
diff
changeset
|
548 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
|
549 ------------------------------- |
|
f0a1b88367b0
coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents:
1130
diff
changeset
|
550 |
|
f0a1b88367b0
coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents:
1130
diff
changeset
|
551 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
|
552 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
|
553 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
|
554 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
|
555 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
|
556 (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
|
557 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
|
558 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
|
559 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
|
560 notifications. |
|
f0a1b88367b0
coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents:
1130
diff
changeset
|
561 |
|
f0a1b88367b0
coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents:
1130
diff
changeset
|
562 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
|
563 `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
|
564 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
|
565 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
|
566 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
|
567 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
|
568 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
|
569 |
|
f0a1b88367b0
coding_style: Looked into feasibility of forcing developers to test their code
Olivier Delalleau <delallea@iro>
parents:
1130
diff
changeset
|
570 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
|
571 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
|
572 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
|
573 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
|
574 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
|
575 - 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
|
576 - 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
|
577 |
|
1140
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
578 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
|
579 ------------------ |
|
7d2e65249bf9
coding_style: Closed some open questions for which a decision was reached during meeting
Olivier Delalleau <delallea@iro>
parents:
1138
diff
changeset
|
580 |
|
1141
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
581 Tasks to be performed by tomorrow: |
|
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
582 * OD: |
|
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
583 * 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
|
584 * Start a file that showcases those guidelines |
|
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
585 * DWF: |
|
6c79394b6b20
coding_style: Decisions made during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1140
diff
changeset
|
586 * 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
|
587 * 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
|
588 * 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
|
589 * 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
|
590 |
|
1170
53340a8df1fa
coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents:
1162
diff
changeset
|
591 Script usage documentation |
|
53340a8df1fa
coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents:
1162
diff
changeset
|
592 -------------------------- |
|
53340a8df1fa
coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents:
1162
diff
changeset
|
593 |
|
53340a8df1fa
coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents:
1162
diff
changeset
|
594 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
|
595 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
|
596 |
|
1178
10bc5ebb5823
coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents:
1170
diff
changeset
|
597 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
|
598 --------------------------------- |
|
10bc5ebb5823
coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents:
1170
diff
changeset
|
599 |
|
10bc5ebb5823
coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents:
1170
diff
changeset
|
600 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
|
601 serializable. |
|
10bc5ebb5823
coding_style: Added note about the need to provide guidelines for serialization-friendly code
Olivier Delalleau <delallea@iro>
parents:
1170
diff
changeset
|
602 |
|
1255
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
603 Meeting 2010/09/24 |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
604 ------------------ |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
605 |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
606 FB: Look into commit guidelines. |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
607 DE: Write guidelines on how to document a class / method (maybe also some |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
608 typical class like an Op) |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
609 DWF: Write guidelines on how to write serializable code |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
610 OD: Finish code sample that showcases all (or many) guidelines, look into |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
611 feasibility of passing arguments to super classes with **kw. |
|
58a6919d3649
coding_style: Added tasks discussed in today's meeting
Olivier Delalleau <delallea@iro>
parents:
1181
diff
changeset
|
612 |
|
1302
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
613 Meeting 2010/10/01 |
|
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
614 ------------------ |
|
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
615 OD: Do your job! |
|
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
616 DE: Send email to ask the lab whether we should go numpy style or theano style |
|
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
617 for class / method documentation, and move guidelines to API file. |
|
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
618 DWF: Finish guidelines for serializable code |
|
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
619 FB: Write guidelines for commits |
|
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
620 |
|
1319
7185d194bb7e
Added question about doc format in file header
Olivier Delalleau <delallea@iro>
parents:
1316
diff
changeset
|
621 Doc format in header? |
|
7185d194bb7e
Added question about doc format in file header
Olivier Delalleau <delallea@iro>
parents:
1316
diff
changeset
|
622 --------------------- |
|
1302
a8f909502886
coding_style: Tasks decided during today's meeting
Olivier Delalleau <delallea@iro>
parents:
1299
diff
changeset
|
623 |
|
1319
7185d194bb7e
Added question about doc format in file header
Olivier Delalleau <delallea@iro>
parents:
1316
diff
changeset
|
624 OD: Should we add in each file's header something like: |
|
7185d194bb7e
Added question about doc format in file header
Olivier Delalleau <delallea@iro>
parents:
1316
diff
changeset
|
625 __docformat__ = "restructuredtext en" |
|
7185d194bb7e
Added question about doc format in file header
Olivier Delalleau <delallea@iro>
parents:
1316
diff
changeset
|
626 |