# HG changeset patch
# User Olivier Delalleau <delallea@iro>
# Date 1284756064 14400
# Node ID ae4b4f7654ec6e036ba96292e0719c0cdadc8113
# Parent  9ebd40d31a1bab2777f7e580949fe545ecbb2df5
coding_style: Updated / closed some points open for debate that were discussed during meeting

diff -r 9ebd40d31a1b -r ae4b4f7654ec doc/v2_planning/coding_style.txt
--- a/doc/v2_planning/coding_style.txt	Fri Sep 17 16:39:29 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Fri Sep 17 16:41:04 2010 -0400
@@ -14,35 +14,13 @@
     * File header:
         - Do we put the accents in 'Universite de Montreal'?
             OD: No (restricting code to ASCII characters is much safer)
+
         - Do we put the Mercurial version number in each file?
             OD: No (useless in my experience, if it's a release the version
                 number can be provided in the README for instance, and in
                 addition Mercurial IDs cannot be easily compared to figure
                 out which of two versions is most recent)
 
-    * Avoid contractions in code comments (particularly in
-      documentation): "We do not add blue to red because it does not look good"
-      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: 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:
         class B(A):
@@ -61,16 +39,48 @@
         - One needs to look at the parent classes to see what these arguments
           are.
         - You cannot use a **kw argument in your constructor for your own
-          selfish purpose.
+          selfish purpose (well, you can actually, but it would look a bit
+          hackish).
         - I have no clue whether one could do this with multiple inheritance.
         - Pb if super class adds an argument that has same name as a child class.
       Question: Should we encourage this in Pylearn?
+      JB: +0.5
+      OD: Was discussed in lab meeting. The feeling was that the last Con was
+          too dangerous. Note however that if we have some system that
+          automatically generates proper doc (i.e. with all arguments, by
+          asking the parent class as well), it could detect the situation
+          mentioned in that last Con (and solve the first one as well).
 
-      JB: +0.5
 
 Closed for public debate
 ------------------------
 
+   * 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: 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: In lab meeting Yoshua ruled out: it is a waste of time to even
+         discuss it. So we let everyone do it the way they like it best.
+
+    * Avoid contractions in code comments (particularly in
+      documentation): "We do not add blue to red because it does not look good"
+      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
+      OD: Discussed in lab meeting, and agreed on.
+
    * Use imports for packages and modules only. I.e. avoid
         from foo import *
         from foo import Bar