--- a/doc/v2_planning/API_coding_style.txt	Fri Sep 17 12:05:31 2010 -0400
+++ b/doc/v2_planning/API_coding_style.txt	Fri Sep 17 12:56:30 2010 -0400
@@ -2,6 +2,10 @@
  Coding Style Guidelines
 =========================
 
+Note: until the Pylearn documentation is properly compiled, you can view
+the HTML version of this document `here
+<http://www.iro.umontreal.ca/~delallea/tmp/coding_style/html/API_coding_style.html>`_.
+
 Main Goals
 ==========
 
@@ -57,6 +61,36 @@
 
         """
 
+    * Standard library imports can (and should) be on the same line, to avoid
+      wasting space on straighforward imports:
+
+      .. code-block:: python
+
+        # Good.
+        import os, sys, time
+        # Good when it does not fit on a single line.
+        import std_lib_module_1, std_lib_module_2, std_lib_module_3
+        import std_lib_module_4, std_lib_module_5, std_lib_module_6
+        # Bad.
+        import os
+        import sys
+        import time
+
+    * Importing class / functions from a module is allowed when these are
+      used multiple times, and no ambiguity is possible.
+
+      .. code-block:: python
+
+        # Good when Bar and Blah are used many times.
+        from foo import Bar, Blah
+        do_something_with(Bar(), Blah(), Bar(), Blah(), Bar(), Blah())
+        # Good in most situations.
+        import foo
+        do_something_with(foo.Bar(), foo.Blah())
+        # Bad.
+        from foo import *
+        from numpy import any   # Potential ambiguity with __builtin__.any
+
 Excerpts
 ~~~~~~~~
 
@@ -83,6 +117,16 @@
       Python versions, and avoids confusion about what is being
       imported.
 
+    * Avoid renaming imported modules. This makes code more difficult to
+      re-use, and is not grep-friendly.
+
+      .. code-block:: python
+
+        # Good.
+        from theano import tensor
+        # Bad.
+        from theano import tensor as T
+
     * Avoid using lists if all you care about is iterating on something. Using
       lists:
 
@@ -177,8 +221,16 @@
 
 Things you should do even if they are not listed in official guidelines:
 
-    * No conditional expression (not supported in Python 2.4). These are
-      expressions of the form ``x = y if condition else z``.
+    * All Python code files should start like this:
+
+      .. code-block:: python
+
+        """Module docstring as the first line, as usual."""
+
+        __authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley"
+        __copyright__ = "(c) 2010, Universite de Montreal"
+        __license__ = "3-clause BSD License"
+        __contact__ = "Name Of Current Guardian of this file <email@address>"
 
     * Use ``//`` for integer division and ``/ float(...)`` if you want the
       floating point operation (for readability and compatibility across all
@@ -228,6 +280,9 @@
         finally:
             always_do_this_regardless_of_what_happened()
 
+    * No conditional expression (not supported in Python 2.4). These are
+      expressions of the form ``x = y if condition else z``.
+
     * Do not use the ``all`` and ``any`` builtin functions (they are not supported
       in Python 2.4). Instead, import them from ``theano.gof.python25`` (or
       use ``numpy.all`` / ``numpy.any`` for array data).
@@ -236,6 +291,13 @@
       probably provide a wrapper around it to be compatible with all Python
       versions.
 
+    * Use ``numpy.inf`` and ``numpy.nan`` rather than
+      ``float('inf')`` / ``float('nan')`` (should be slightly more efficient even
+      if efficiency is typically not an issue here, the main goal being code
+      consistency). Also, always use ``numpy.isinf`` / ``numpy.isnan`` to
+      test infinite / NaN values. This is important because ``numpy.nan !=
+      float('nan')``.
+
     * 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).
@@ -393,3 +455,21 @@
 
     import os, sys, time
 
+Automatic Code Verification
+===========================
+
+Tools will be available to make it easier to automatically ensure that code
+committed to Pylearn complies to above specifications. This work is not
+finalized yet, but David started a `Wiki page`_ with helpful configuration
+tips for Vim.
+
+.. _Wiki page: http://www.iro.umontreal.ca/~lisa/twiki/bin/view.cgi/Divers/VimPythonRecommendations
+
+TODO
+====
+
+Things still missing from this document, being discussed in coding_style.txt:
+    - Proper style for C code and Mercurial commits
+    - Enforcing 100% test coverage of the code base
+    - Providing ways to add type checking for function arguments
+