# HG changeset patch # User James Bergstra # Date 1284485402 14400 # Node ID 60ef81fe1825b301654a9f1a4ec5cdbaeb4886c8 # Parent 1ed0719cfbce0a234ac05eb5a8c461ab0dd3fb62 2cents in coding_style diff -r 1ed0719cfbce -r 60ef81fe1825 doc/v2_planning/coding_style.txt --- a/doc/v2_planning/coding_style.txt Tue Sep 14 13:05:58 2010 -0400 +++ b/doc/v2_planning/coding_style.txt Tue Sep 14 13:30:02 2010 -0400 @@ -24,6 +24,15 @@ when you want to copy / paste different pieces of code and they use different conventions. Typing tensor.* is a bit longer, but a lot more portable. + JB: I thought that these are nice: + - "from foo import Bar" + - "from foo import Bar, Blah" + What's wrong with them? They keep the code listing short and readable. + I would discourage these forms when symbols 'Bar' and 'Blah' are + ambiguous, in which case the parent module prefix serves to disambiguate + them in the code. + I agree that the "import A as B" form should be discouraged in general, + because that's just confusing and makes code less grep-friendly. * Imports should usually be on separate lines. OD: I would add an exception, saying it is ok to group multiple imports @@ -34,6 +43,7 @@ makes dependencies clearer, and diffs look better when someone adds / removes an import). Does anyone see a good reason to keep standard library imports on different lines? + JB: what does 'usually' mean here? The guideline seems vacuous. * The BDFL recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing @@ -47,12 +57,15 @@ rather than "We don't add blue to red because it doesn't look good". OD: I mostly find it to be cleaner (been used to it while writing scientific articles too). + JB: +1 * Imperative vs. third-person comments. # Return the sum of elements in x. <-- imperative # Returns the sum of elements in x. <-- third-person OD: I am used to the imperative form and like it better only because it typically saves one letter (the 's') and is easier to conjugate. + JB: What about being compatible with markup formats that have a :returns: + tag? * OD: I like always doing the following when subclassing a class A: @@ -77,6 +90,13 @@ - More? Question: Should we encourage this in Pylearn? + JB: +0.5 + + * JB: How should we combine capitalization and underscores to name classes + and functions related to an algorithm like 'SGD' or a model like 'RBM' + whose common name is capitalized? Case in point: How should I name a + Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation? + Note about warnings -------------------