# HG changeset patch
# User Olivier Delalleau <delallea@iro>
# Date 1284667922 14400
# Node ID d693881ea4d2c32c85aba90929c17d068026c770
# Parent  d6d73a9f07b8ae097eb22652b22a02184fbdaeb4# Parent  1679742e7aa1bf642346373f6b69fff505441569
Merged

diff -r d6d73a9f07b8 -r d693881ea4d2 doc/v2_planning/coding_style.txt
--- a/doc/v2_planning/coding_style.txt	Thu Sep 16 16:11:26 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Thu Sep 16 16:12:02 2010 -0400
@@ -520,4 +520,74 @@
         * Make public some configuration files / plugins for vim
         * Come up with official common file header (license in particular)
 
+Extended docstring standard (DWF)
+---------------------------------
 
+In addition to the general guidelines of PEP 257, it is advised that we adopt
+the NumPy docstring standard, or at least use it as a basis for formulating
+our own.
+
+Read the detailed docstring standard at
+
+http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
+
+
+logging module, the warning module, and when to use which
+---------------------------------------------------------
+
+The logging module
+##################
+
+A central logging facility for Python capable of logging messages of various
+categories/urgency and choosing with some granularity which messages are
+displayed/suppressed, as well as where they are displayed or written. This
+includes an "INFO" level for innocuous status information, a "WARNING" level
+for unexpected state that is still recoverable, "DEBUG" for detailed
+information which is only really of interest when things are going wrong, etc.
+
+In addition to the `library documentation`_, see this helpful tutorial,
+`Python Logging 101`_.
+
+.. _library documentation: http://docs.python.org/library/logging.html
+.. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html
+
+The warning module
+##################
+
+The warning module in the standard library and its main interface, the
+warn() function, allows the programmer to issue warnings in situations where
+they wish to alert the user to some condition, but the situation is not
+urgent enough to throw an exception. By default, a warning issued at a given
+line of the code will only be displayed the first time that line is executed.
+By default, warnings are written to sys.stderr but the warning module
+contains flexible facilities for altering the defaults, redirecting, etc.
+
+Which? When?
+############
+
+It's our feeling that the logging module's WARNING level be used to log
+warnings more meant for *internal*, *developer* consumption, to log situations
+where something unexpected happened that may be indicative of a problem but
+it's several layers of abstraction below what a user of the library would
+care about.
+
+By contrast, the warning module should be used for warnings intended for user
+consumption, e.g. alerting them that their version of pylearn is older than
+this plugin requires, so things may not work as expected, or that a given
+function/class/method is slated for deprecation in a coming release (early
+in the library's lifetime, DeprecationWarnings will likely be the most common
+case). The warning message issued through this facility should avoid
+referring to pylearn internals.
+
+Suggested per-file boilerplate
+------------------------------
+
+"""Module docstring as the first line, as usual."""
+
+__authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley"
+__copyright__ = "(c) 2010, Université de Montréal"
+__license__ = "3-clause BSD License"
+__contact__ = "Name Of Current Guardian of this file <email@address>"
+
+We could also pull Mercurial revision info and put it in __version__, this
+seems to be common.