changeset 1170:53340a8df1fa

coding_style: Started to write full code sample
author Olivier Delalleau <delallea@iro>
date Fri, 17 Sep 2010 14:37:00 -0400
parents ec1e93663656
children fab72f424ee0
files doc/v2_planning/API_coding_style.txt doc/v2_planning/coding_style.txt
diffstat 2 files changed, 53 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- 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
 
--- 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.
+