# HG changeset patch
# User Olivier Delalleau <delallea@iro>
# Date 1284748620 14400
# Node ID 53340a8df1faadfe98662ec92f5e0ab6321d102c
# Parent  ec1e93663656c3aaa28020903092c2ec59024b21
coding_style: Started to write full code sample

diff -r ec1e93663656 -r 53340a8df1fa doc/v2_planning/API_coding_style.txt
--- a/doc/v2_planning/API_coding_style.txt	Fri Sep 17 12:56:43 2010 -0400
+++ b/doc/v2_planning/API_coding_style.txt	Fri Sep 17 14:37:00 2010 -0400
@@ -448,13 +448,57 @@
 Code Sample
 ===========
 
-The following code sample illustrates many of the coding guidelines one should
-follow in Pylearn.
+The following code sample illustrates some of the coding guidelines one should
+follow in Pylearn. This is still a work-in-progress.
 
 .. code-block:: python
 
+    #! /usr/env/bin python
+
+    """Sample code. There may still be mistakes / missing elements."""
+
+    __authors__ = "Olivier Delalleau"
+    __copyright__ = "(c) 2010, Universite de Montreal"
+    __license__ = "3-clause BSD License"
+    __contact__ = "Olivier Delalleau <delallea@iro>"
+
+    # Standard library imports are on a single line.
     import os, sys, time
 
+    # Third-party imports come after standard library imports, and there is
+    # only one import per line. Imports are sorted lexicographically.
+    import numpy
+    import scipy
+    import theano
+    # Put 'from' imports below.
+    from numpy import argmax
+    from theano import tensor
+    
+    # Application-specific imports come last.
+    from pylearn import dataset
+    from pylearn.optimization import minimize
+
+    def print_files_in(directory):
+        """Print the first line of each file in given directory."""
+        # TODO To be continued...
+
+    def main():
+        if len(sys.argv) != 2:
+            # Note: conventions on how to display script documentation and
+            # parse arguments are still to-be-determined.
+            print("""\
+    Usage: %s <directory>
+    Print first line of each file in given directory (in alphabetic order)."""
+                  % os.path.basename(sys.argv[0]))
+            return 1
+        print_files_in(sys.argv[1])
+        return 0
+
+    # Top-level executable code should be minimal.
+    if __name__ == '__main__':
+        sys.exit(main())
+    
+
 Automatic Code Verification
 ===========================
 
@@ -472,4 +516,5 @@
     - 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
+    - Conventions for script usage documentation and argument parsing
 
diff -r ec1e93663656 -r 53340a8df1fa doc/v2_planning/coding_style.txt
--- a/doc/v2_planning/coding_style.txt	Fri Sep 17 12:56:43 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Fri Sep 17 14:37:00 2010 -0400
@@ -478,3 +478,9 @@
         * Make public some configuration files / plugins for vim
         * Come up with official common file header (license in particular)
 
+Script usage documentation
+--------------------------
+
+OD: It would be nice to have some standardized way of parsing a script's
+arguments and displaying the script usage doc to the user.
+