Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1140:7d2e65249bf9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Closed some open questions for which a decision was reached during meeting
author Olivier Delalleau <delallea@iro>
date Thu, 16 Sep 2010 13:14:19 -0400
parents 9583e908c572
children 6c79394b6b20
comparison
equal deleted inserted replaced
1138:9583e908c572 1140:7d2e65249bf9
8 - David 8 - David
9 - Olivier D [leader] 9 - Olivier D [leader]
10 10
11 Open for public debate 11 Open for public debate
12 ---------------------- 12 ----------------------
13
14 * Avoid contractions in code comments (particularly in
15 documentation): "We do not add blue to red because it does not look good"
16 rather than "We don't add blue to red because it doesn't look good".
17 OD: I mostly find it to be cleaner (been used to it while writing
18 scientific articles too).
19 JB: +1
20
21 * Imperative vs. third-person comments.
22 # Return the sum of elements in x. <-- imperative
23 # Returns the sum of elements in x. <-- third-person
24 OD: I am used to the imperative form and like it better only because it
25 typically saves one letter (the 's') and is easier to conjugate.
26 JB: What about being compatible with markup formats that have a :returns:
27 tag?
28 OD: That'd make sense. However, when I wrote the above I hadn't looked
29 closely at PEP257 yet, and I just noticed the following official
30 recommendation for one-line docstrings in it:
31 The docstring is a phrase ending in a period. It prescribes the
32 function or method's effect as a command ("Do this", "Return that"), not as a
33 description; e.g. don't write "Returns the pathname ...".
34 Anyone knows which style is most popular in the open-source
35 community?
36
37 * OD: I like always doing the following when subclassing
38 a class A:
39 class B(A):
40 def __init__(self, b_arg_1, b_arg_2, **kw):
41 super(B, self).__init__(**kw)
42 ...
43 The point here is that the constructor always allow for extra keyword
44 arguments (except for the class at the very top of the hierarchy), which
45 are automatically passed to the parent class.
46 Pros:
47 - You do not need to repeat the parent class arguments whenever you
48 write a new subclass.
49 - Whenever you add an argument to the parent class, all child classes
50 can benefit from it without modifying their code.
51 Cons:
52 - One needs to look at the parent classes to see what these arguments
53 are.
54 - You cannot use a **kw argument in your constructor for your own
55 selfish purpose.
56 - I have no clue whether one could do this with multiple inheritance.
57 - More?
58 Question: Should we encourage this in Pylearn?
59
60 JB: +0.5
61
62 Closed for public debate
63 ------------------------
13 64
14 * Use imports for packages and modules only. I.e. avoid 65 * Use imports for packages and modules only. I.e. avoid
15 from foo import * 66 from foo import *
16 from foo import Bar 67 from foo import Bar
17 OD: Overall I agree with this. However we probably want to allow some 68 OD: Overall I agree with this. However we probably want to allow some
38 and would vote in favor of accepting it when it is appropriate. 89 and would vote in favor of accepting it when it is appropriate.
39 This guideline was taken from Google's coding recommendation: 90 This guideline was taken from Google's coding recommendation:
40 "from foo import * or from foo import Bar is very nasty and can 91 "from foo import * or from foo import Bar is very nasty and can
41 lead to serious maintenance issues because it makes it hard to find 92 lead to serious maintenance issues because it makes it hard to find
42 module dependencies." 93 module dependencies."
94 OD: Decision was taken in committee's meeting to allow
95 from foo import Bar, Blah
96 when imported stuff is re-used multiple times in the same file, and
97 there is no ambiguity.
43 98
44 * Imports should usually be on separate lines. 99 * Imports should usually be on separate lines.
45 OD: I would add an exception, saying it is ok to group multiple imports 100 OD: I would add an exception, saying it is ok to group multiple imports
46 from the standard library on a single line, e.g. 101 from the standard library on a single line, e.g.
47 import os, sys, time 102 import os, sys, time
54 OD: Sorry my fault, I did not quote the whole guideline from PEP8. The 109 OD: Sorry my fault, I did not quote the whole guideline from PEP8. The
55 'usually' was because of what followed: 110 'usually' was because of what followed:
56 it's okay to say this though: 111 it's okay to say this though:
57 from subprocess import Popen, PIPE 112 from subprocess import Popen, PIPE
58 (which btw contradicts Google's recommendation mentioned previously) 113 (which btw contradicts Google's recommendation mentioned previously)
114 OD: Decision was taken in committee's meeting to allow multiple imports
115 on the same line for standard library modules (only).
59 116
60 * The BDFL recommends inserting a blank line between the 117 * The BDFL recommends inserting a blank line between the
61 last paragraph in a multi-line docstring and its closing quotes, placing 118 last paragraph in a multi-line docstring and its closing quotes, placing
62 the closing quotes on a line by themselves. This way, Emacs' 119 the closing quotes on a line by themselves. This way, Emacs'
63 fill-paragraph command can be used on it. 120 fill-paragraph command can be used on it.
64 OD: I think it is ugly and I have not seen it used much. Any Emacs 121 OD: I think it is ugly and I have not seen it used much. Any Emacs
65 user believes it is a must? 122 user believes it is a must?
66 123 OD: Decision was taken in committee's meeting to drop this
67 * Avoid contractions in code comments (particularly in 124 recommendation.
68 documentation): "We do not add blue to red because it does not look good"
69 rather than "We don't add blue to red because it doesn't look good".
70 OD: I mostly find it to be cleaner (been used to it while writing
71 scientific articles too).
72 JB: +1
73
74 * Imperative vs. third-person comments.
75 # Return the sum of elements in x. <-- imperative
76 # Returns the sum of elements in x. <-- third-person
77 OD: I am used to the imperative form and like it better only because it
78 typically saves one letter (the 's') and is easier to conjugate.
79 JB: What about being compatible with markup formats that have a :returns:
80 tag?
81 OD: That'd make sense. However, when I wrote the above I hadn't looked
82 closely at PEP257 yet, and I just noticed the following official
83 recommendation for one-line docstrings in it:
84 The docstring is a phrase ending in a period. It prescribes the
85 function or method's effect as a command ("Do this", "Return that"), not as a
86 description; e.g. don't write "Returns the pathname ...".
87 Anyone knows which style is most popular in the open-source
88 community?
89
90 * OD: I like always doing the following when subclassing
91 a class A:
92 class B(A):
93 def __init__(self, b_arg_1, b_arg_2, **kw):
94 super(B, self).__init__(**kw)
95 ...
96 The point here is that the constructor always allow for extra keyword
97 arguments (except for the class at the very top of the hierarchy), which
98 are automatically passed to the parent class.
99 Pros:
100 - You do not need to repeat the parent class arguments whenever you
101 write a new subclass.
102 - Whenever you add an argument to the parent class, all child classes
103 can benefit from it without modifying their code.
104 Cons:
105 - One needs to look at the parent classes to see what these arguments
106 are.
107 - You cannot use a **kw argument in your constructor for your own
108 selfish purpose.
109 - I have no clue whether one could do this with multiple inheritance.
110 - More?
111 Question: Should we encourage this in Pylearn?
112
113 JB: +0.5
114 125
115 * JB: How should we combine capitalization and underscores to name classes 126 * JB: How should we combine capitalization and underscores to name classes
116 and functions related to an algorithm like 'SGD' or a model like 'RBM' 127 and functions related to an algorithm like 'SGD' or a model like 'RBM'
117 whose common name is capitalized? Case in point: How should I name a 128 whose common name is capitalized? Case in point: How should I name a
118 Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation? 129 Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation?
124 All identifiers in the Python standard library (...) SHOULD use 135 All identifiers in the Python standard library (...) SHOULD use
125 English words wherever feasible (in many cases, abbreviations and 136 English words wherever feasible (in many cases, abbreviations and
126 technical terms are used which aren't English). 137 technical terms are used which aren't English).
127 so I guess HMC is ok when using Hybrid Monte Carlo is considered to 138 so I guess HMC is ok when using Hybrid Monte Carlo is considered to
128 make some names too long. 139 make some names too long.
140
129 141
130 Note about warnings 142 Note about warnings
131 ------------------- 143 -------------------
132 144
133 Fred: This is a refactored thing from James email of what we should put in message 145 Fred: This is a refactored thing from James email of what we should put in message
475 different policy about lack-of-coverage notification emails, depending on 487 different policy about lack-of-coverage notification emails, depending on
476 whether or not the warning is present: 488 whether or not the warning is present:
477 - if there is no warning, daily email notification (ADD A WARNING!!!) 489 - if there is no warning, daily email notification (ADD A WARNING!!!)
478 - if there is a warning, weekly email notification (ADD A TEST!!!) 490 - if there is a warning, weekly email notification (ADD A TEST!!!)
479 491
492 Meeting 2010/09/16
493 ------------------
494
495 (in progress)
496