Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1113:60ef81fe1825

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
2cents in coding_style
author James Bergstra <bergstrj@iro.umontreal.ca>
date Tue, 14 Sep 2010 13:30:02 -0400
parents 56c5f0990869
children 1a1c0c3adcca
comparison
equal deleted inserted replaced
1112:1ed0719cfbce 1113:60ef81fe1825
22 but I would prefer to forbid this. It is handy when trying stuff in 22 but I would prefer to forbid this. It is handy when trying stuff in
23 the interactive interpreter, but in real code it can easily get messy 23 the interactive interpreter, but in real code it can easily get messy
24 when you want to copy / paste different pieces of code and they use 24 when you want to copy / paste different pieces of code and they use
25 different conventions. Typing tensor.* is a bit longer, but a lot more 25 different conventions. Typing tensor.* is a bit longer, but a lot more
26 portable. 26 portable.
27 JB: I thought that these are nice:
28 - "from foo import Bar"
29 - "from foo import Bar, Blah"
30 What's wrong with them? They keep the code listing short and readable.
31 I would discourage these forms when symbols 'Bar' and 'Blah' are
32 ambiguous, in which case the parent module prefix serves to disambiguate
33 them in the code.
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.
27 36
28 * Imports should usually be on separate lines. 37 * Imports should usually be on separate lines.
29 OD: I would add an exception, saying it is ok to group multiple imports 38 OD: I would add an exception, saying it is ok to group multiple imports
30 from the standard library on a single line, e.g. 39 from the standard library on a single line, e.g.
31 import os, sys, time 40 import os, sys, time
32 I just don't see much benefit in putting them on separate lines (for 41 I just don't see much benefit in putting them on separate lines (for
33 third-party imports I agree it is best to keep them separate, as it 42 third-party imports I agree it is best to keep them separate, as it
34 makes dependencies clearer, and diffs look better when someone adds / 43 makes dependencies clearer, and diffs look better when someone adds /
35 removes an import). Does anyone see a good reason to keep standard 44 removes an import). Does anyone see a good reason to keep standard
36 library imports on different lines? 45 library imports on different lines?
46 JB: what does 'usually' mean here? The guideline seems vacuous.
37 47
38 * The BDFL recommends inserting a blank line between the 48 * The BDFL recommends inserting a blank line between the
39 last paragraph in a multi-line docstring and its closing quotes, placing 49 last paragraph in a multi-line docstring and its closing quotes, placing
40 the closing quotes on a line by themselves. This way, Emacs' 50 the closing quotes on a line by themselves. This way, Emacs'
41 fill-paragraph command can be used on it. 51 fill-paragraph command can be used on it.
45 * Avoid contractions in code comments (particularly in 55 * Avoid contractions in code comments (particularly in
46 documentation): "We do not add blue to red because it does not look good" 56 documentation): "We do not add blue to red because it does not look good"
47 rather than "We don't add blue to red because it doesn't look good". 57 rather than "We don't add blue to red because it doesn't look good".
48 OD: I mostly find it to be cleaner (been used to it while writing 58 OD: I mostly find it to be cleaner (been used to it while writing
49 scientific articles too). 59 scientific articles too).
60 JB: +1
50 61
51 * Imperative vs. third-person comments. 62 * Imperative vs. third-person comments.
52 # Return the sum of elements in x. <-- imperative 63 # Return the sum of elements in x. <-- imperative
53 # Returns the sum of elements in x. <-- third-person 64 # Returns the sum of elements in x. <-- third-person
54 OD: I am used to the imperative form and like it better only because it 65 OD: I am used to the imperative form and like it better only because it
55 typically saves one letter (the 's') and is easier to conjugate. 66 typically saves one letter (the 's') and is easier to conjugate.
67 JB: What about being compatible with markup formats that have a :returns:
68 tag?
56 69
57 * OD: I like always doing the following when subclassing 70 * OD: I like always doing the following when subclassing
58 a class A: 71 a class A:
59 class B(A): 72 class B(A):
60 def __init__(self, b_arg_1, b_arg_2, **kw): 73 def __init__(self, b_arg_1, b_arg_2, **kw):
75 selfish purpose. 88 selfish purpose.
76 - I have no clue whether one could do this with multiple inheritance. 89 - I have no clue whether one could do this with multiple inheritance.
77 - More? 90 - More?
78 Question: Should we encourage this in Pylearn? 91 Question: Should we encourage this in Pylearn?
79 92
93 JB: +0.5
94
95 * 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'
97 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?
99
80 Note about warnings 100 Note about warnings
81 ------------------- 101 -------------------
82 102
83 Fred: This is a refactored thing from James email of what we should put in message 103 Fred: This is a refactored thing from James email of what we should put in message
84 that we send to the user: 104 that we send to the user: