# HG changeset patch
# User Olivier Delalleau <delallea@iro>
# Date 1284566769 14400
# Node ID 03b41a79bd601d63264cbe0a810636808d457c75
# Parent  7207f86a661ff4b0ef8d335fa9e74a2f31af1e2d
coding_style: Replies to James' questions / comments

diff -r 7207f86a661f -r 03b41a79bd60 doc/v2_planning/coding_style.txt
--- a/doc/v2_planning/coding_style.txt	Wed Sep 15 11:45:14 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Wed Sep 15 12:06:09 2010 -0400
@@ -33,6 +33,13 @@
         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.
+     OD: I agree that "from foo import Bar, Blah" is sometimes convenient
+        (typically when you re-use Bar / Blah many times in the same file),
+        and would vote in favor of accepting it when it is appropriate.
+        This guideline was taken from Google's coding recommendation:
+            "from foo import * or from foo import Bar is very nasty and can
+             lead to serious maintenance issues because it makes it hard to find
+             module dependencies."
 
    * Imports should usually be on separate lines.
      OD: I would add an exception, saying it is ok to group multiple imports
@@ -44,6 +51,11 @@
         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.
+     OD: Sorry my fault, I did not quote the whole guideline from PEP8. The
+         'usually' was because of what followed:
+            it's okay to say this though:
+                from subprocess import Popen, PIPE
+         (which btw contradicts Google's recommendation mentioned previously)
 
     * The BDFL recommends inserting a blank line between the
       last paragraph in a multi-line docstring and its closing quotes, placing
@@ -66,6 +78,14 @@
          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: That'd make sense. However, when I wrote the above I hadn't looked
+         closely at PEP257 yet, and I just noticed the following official
+         recommendation for one-line docstrings in it:
+            The docstring is a phrase ending in a period. It prescribes the
+            function or method's effect as a command ("Do this", "Return that"), not as a
+            description; e.g. don't write "Returns the pathname ...".
+         Anyone knows which style is most popular in the open-source
+         community?
 
     * OD: I like always doing the following when subclassing
       a class A:
@@ -96,6 +116,16 @@
           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?
+      OD: This one is answered by PEP8 (search HTTPServerError in it).
+          You should use:
+            RBMClassName
+            rbm_function_name
+          As far as using abbreviations is concerned:
+            All identifiers in the Python standard library (...) SHOULD use
+            English words wherever feasible (in many cases, abbreviations and
+            technical terms are used which aren't English).
+          so I guess HMC is ok when using Hybrid Monte Carlo is considered to
+          make some names too long.
 
 Note about warnings
 -------------------