Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1128:03b41a79bd60

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Replies to James' questions / comments
author Olivier Delalleau <delallea@iro>
date Wed, 15 Sep 2010 12:06:09 -0400
parents 1a1c0c3adcca
children aae62c4b2e9f
comparison
equal deleted inserted replaced
1127:7207f86a661f 1128:03b41a79bd60
31 I would discourage these forms when symbols 'Bar' and 'Blah' are 31 I would discourage these forms when symbols 'Bar' and 'Blah' are
32 ambiguous, in which case the parent module prefix serves to disambiguate 32 ambiguous, in which case the parent module prefix serves to disambiguate
33 them in the code. 33 them in the code.
34 I agree that the "import A as B" form should be discouraged in general, 34 I agree that the "import A as B" form should be discouraged in general,
35 because that's just confusing and makes code less grep-friendly. 35 because that's just confusing and makes code less grep-friendly.
36 OD: I agree that "from foo import Bar, Blah" is sometimes convenient
37 (typically when you re-use Bar / Blah many times in the same file),
38 and would vote in favor of accepting it when it is appropriate.
39 This guideline was taken from Google's coding recommendation:
40 "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
42 module dependencies."
36 43
37 * Imports should usually be on separate lines. 44 * Imports should usually be on separate lines.
38 OD: I would add an exception, saying it is ok to group multiple imports 45 OD: I would add an exception, saying it is ok to group multiple imports
39 from the standard library on a single line, e.g. 46 from the standard library on a single line, e.g.
40 import os, sys, time 47 import os, sys, time
42 third-party imports I agree it is best to keep them separate, as it 49 third-party imports I agree it is best to keep them separate, as it
43 makes dependencies clearer, and diffs look better when someone adds / 50 makes dependencies clearer, and diffs look better when someone adds /
44 removes an import). Does anyone see a good reason to keep standard 51 removes an import). Does anyone see a good reason to keep standard
45 library imports on different lines? 52 library imports on different lines?
46 JB: what does 'usually' mean here? The guideline seems vacuous. 53 JB: what does 'usually' mean here? The guideline seems vacuous.
54 OD: Sorry my fault, I did not quote the whole guideline from PEP8. The
55 'usually' was because of what followed:
56 it's okay to say this though:
57 from subprocess import Popen, PIPE
58 (which btw contradicts Google's recommendation mentioned previously)
47 59
48 * The BDFL recommends inserting a blank line between the 60 * The BDFL recommends inserting a blank line between the
49 last paragraph in a multi-line docstring and its closing quotes, placing 61 last paragraph in a multi-line docstring and its closing quotes, placing
50 the closing quotes on a line by themselves. This way, Emacs' 62 the closing quotes on a line by themselves. This way, Emacs'
51 fill-paragraph command can be used on it. 63 fill-paragraph command can be used on it.
64 # Returns the sum of elements in x. <-- third-person 76 # Returns the sum of elements in x. <-- third-person
65 OD: I am used to the imperative form and like it better only because it 77 OD: I am used to the imperative form and like it better only because it
66 typically saves one letter (the 's') and is easier to conjugate. 78 typically saves one letter (the 's') and is easier to conjugate.
67 JB: What about being compatible with markup formats that have a :returns: 79 JB: What about being compatible with markup formats that have a :returns:
68 tag? 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?
69 89
70 * OD: I like always doing the following when subclassing 90 * OD: I like always doing the following when subclassing
71 a class A: 91 a class A:
72 class B(A): 92 class B(A):
73 def __init__(self, b_arg_1, b_arg_2, **kw): 93 def __init__(self, b_arg_1, b_arg_2, **kw):
94 114
95 * JB: How should we combine capitalization and underscores to name classes 115 * JB: How should we combine capitalization and underscores to name classes
96 and functions related to an algorithm like 'SGD' or a model like 'RBM' 116 and functions related to an algorithm like 'SGD' or a model like 'RBM'
97 whose common name is capitalized? Case in point: How should I name a 117 whose common name is capitalized? Case in point: How should I name a
98 Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation? 118 Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation?
119 OD: This one is answered by PEP8 (search HTTPServerError in it).
120 You should use:
121 RBMClassName
122 rbm_function_name
123 As far as using abbreviations is concerned:
124 All identifiers in the Python standard library (...) SHOULD use
125 English words wherever feasible (in many cases, abbreviations and
126 technical terms are used which aren't English).
127 so I guess HMC is ok when using Hybrid Monte Carlo is considered to
128 make some names too long.
99 129
100 Note about warnings 130 Note about warnings
101 ------------------- 131 -------------------
102 132
103 Fred: This is a refactored thing from James email of what we should put in message 133 Fred: This is a refactored thing from James email of what we should put in message