# HG changeset patch
# User Olivier Delalleau <delallea@iro>
# Date 1284048109 14400
# Node ID b4ccf6b43f272dae8956f477a5603fa87d9764f6
# Parent  bc3f7834db83042670503be377b9d033e809d0c1
coding_style: Added some comments about PEP8

diff -r bc3f7834db83 -r b4ccf6b43f27 doc/v2_planning/coding_style.txt
--- a/doc/v2_planning/coding_style.txt	Wed Sep 08 20:45:17 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Thu Sep 09 12:01:49 2010 -0400
@@ -12,6 +12,7 @@
 ----------------------------------------------------------
 
     * http://www.python.org/dev/peps/pep-0008/
+    * http://www.python.org/dev/peps/pep-0257/
     * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
     * http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
     * http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
@@ -31,6 +32,64 @@
 Dumi: we should also try to find tools that automate these
 processes: pylint, pyflakes, pychecker, pythontidy
 
+OD: I think PEP8 + Google guidelines are a good basis.
+OD: Things about PEP 8 I don't like (but it may be just me):
+
+   * If necessary, you can add an extra pair of parentheses around an
+     expression, but sometimes using a backslash looks better.
+    --> I rarely find that backslash looks better. In most situations you can
+        get rid of them. Typically I prefer:
+            if (cond_1 and
+                cond_2 and
+                cond_3):
+        to
+            if cond_1 and \
+               cond_2 and \
+               cond_3:
+
+   * You should use two spaces after a sentence-ending period.
+    --> Looks weird to me.
+
+   * Imports should usually be on separate lines
+    --> Can be a lot of lines wasted for no obvious benefit. I think this is
+        mostly useful when you import different modules from different places,
+        but I would say that for instance for standard modules it would be
+        better to import them all on a single line (doing multiple lines only
+        if there are too many of them), e.g. prefer:
+            import os, sys, time
+        to
+            import os
+            import sys
+            import time
+        However, I agree about separating imports between standard lib / 3rd
+        party, e.g. prefer:
+            import os, sys, time
+            import numpy, scipy
+        to
+            import numpy, os, scipy, sys, time
+        (Personal note: preferably order imports by alphabetical order, makes
+         it easier to quickly see if a specific module is already imported,
+         and avoids duplicated imports)
+
+    * Missing in PEP 8:
+        - How to indent multi-line statements? E.g. do we want
+            x = my_func(a, b, c,
+                d, e, f)
+          or
+            x = my_func(a, b, c,
+                        d, e, f)
+          or
+            x = my_func(
+                a, b, c, d, e, f)
+          --> Probably depends on the specific situation, but we could have a
+            few typical examples (and the same happens with multi-lines lists)
+
+    * From PEP 257: The BDFL [3] recommends inserting a blank line between the
+      last paragraph in a multi-line docstring and its closing quotes, placing
+      the closing quotes on a line by themselves. This way, Emacs'
+      fill-paragraph command can be used on it.
+     --> I have nothing against Emacs, but this is ugly!
+
 Documentation
 -------------
 
@@ -52,5 +111,5 @@
 Meetings
 --------
 
-Next meeting: Thursday 2010/09/09, 11 am
+   * Thursday 2010/09/09, 11 am