# HG changeset patch
# User Olivier Delalleau <delallea@iro>
# Date 1284667886 14400
# Node ID d6d73a9f07b8ae097eb22652b22a02184fbdaeb4
# Parent  fa1715e759e3457c8186c78bf76a0faef9e52f76
API_coding_style: Started to work on official guidelines

diff -r fa1715e759e3 -r d6d73a9f07b8 doc/v2_planning/API_coding_style.txt
--- a/doc/v2_planning/API_coding_style.txt	Thu Sep 16 14:17:34 2010 -0400
+++ b/doc/v2_planning/API_coding_style.txt	Thu Sep 16 16:11:26 2010 -0400
@@ -2,6 +2,18 @@
  Coding Style Guidelines
 =========================
 
+Main Goals
+==========
+
+    * Code should be compatible with Python 2.4 and above (using 2to3 for
+      conversion to Python 3.x). This may not be possible in the short term
+      for code dependent on Theano.
+
+    * Code should be easy to read, understand and update by developers and
+      users.
+
+    * Code should be well-documented and well-tested.
+
 Code Sample
 ===========
 
@@ -12,4 +24,86 @@
 
     import os, sys, time
 
+Python Coding Guidelines
+========================
 
+Official Guidelines
+-------------------
+
+Source Material
+~~~~~~~~~~~~~~~
+
+The three main documents describing our Python coding guidelines are:
+    * `PEP 8 -- Style Guide for Python Code
+      <http://www.python.org/dev/peps/pep-0008>`_
+    * `PEP 257 -- Docstring Conventions
+      <http://www.python.org/dev/peps/pep-0257>`_
+    * `Google Python Style Guide
+      <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_
+
+However, there are a few points mentioned in those documents that we decided
+to do differently:
+
+    * Use only one space (not two) after a sentence-ending period in comments.
+
+Excerpts
+~~~~~~~~
+
+We emphasize here a few important topics that are found in the official
+guidelines:
+
+Additional Recommendations
+--------------------------
+
+Things you should do even if they are not listed in official guidelines:
+
+    * Avoid backslashes whenever possible. They make it more
+      difficult to edit code, and they are ugly (as well as potentially
+      dangerous if there are trailing white spaces).
+
+      .. code-block:: python
+
+        # Good.
+        if (cond_1 and
+            cond_2 and
+            cond_3):
+            ... 
+        # Bad.
+        if cond_1 and \
+           cond_2 and \
+           cond_3:
+            ...
+
+    * When indenting multi-line statements like lists or function arguments,
+      keep elements of the same level aligned with each other.
+      The position of the first
+      element (on the same line or a new line) should be chosen depending on
+      what is easiest to read (sometimes both can be ok).
+
+      .. code-block:: python
+
+        # Good.
+        for my_very_long_variable_name in [my_food, my_bar, my_love,
+                                           my_everything]:
+            ...
+        for my_very_long_variable_name in [
+                my_foo, my_bar, my_love, my_everything]:
+            ...
+        # Good iff the list needs to be frequently updated.
+        for my_very_long_variable_name in [
+                my_foo,
+                my_bar,
+                my_love,
+                my_everything,
+                ]:
+            ...
+        # Bad.
+        for my_very_long_variable_name in [my_foo, my_bar, my_love,
+                my_everything]:
+            ...
+        for my_very_long_variable_name in [my_foo,
+                                           my_bar,
+                                           my_love,
+                                           my_everything]:
+            ...
+