--- a/doc/v2_planning/coding_style.txt	Thu Sep 16 23:42:26 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Fri Sep 17 16:09:02 2010 +0300
@@ -174,9 +174,6 @@
 We will probably want to take PEP-8 as starting point, and read what other
 people think about it / how other coding guidelines differ from it.
 
-Dumi: we should also try to find tools that automate these
-processes: pylint, pyflakes, pychecker, pythontidy
-
 OD: Things about PEP 8 I don't like (but it may be just me):
 
    * If necessary, you can add an extra pair of parentheses around an
@@ -269,6 +266,8 @@
    * Automatized code verification
 Use pychecker & friends to make sure everything is fine.
 Task: Look into the various options available (DE)
+Result: See sections 'Tools to help us out' and 'Automating and enforcing coding
+style'
 
    * Tests
 Force people to write tests. Automatic email reminder of code lines not
@@ -399,6 +398,85 @@
 During committee's meeting, Fred mentioned a bug with Assembla links for
 multi-line commits.
 
+Tools to help us out
+---------------------
+
+Dumi:
+
+  * pylint: highly configurable and very popular tool, similar in spirit to lint
+  for C. Can specify a config file, customize/disable warnings and errors, hook
+  it to vim/emacs and include coding style convensions in the check too. A nice
+  feature is that you can include a comment like "# pylint: disable-msg=C0103"
+  into a file and disable a message locally. This is nice and dangerous at the
+  same time. Another cool feature is incremental checking with caching of
+  results, which also allows tracking of progress.
+
+  * pyflakes: pylint alternative that is supposedly faster, but is I think more
+  limited in the number of things it is good at: "PyFlakes will tell you when
+  you have forgotten an import, mistyped a variable name, defined two functions
+  with the same name, shadowed a variable from another scope, imported a module
+  twice, or two different modules with the same name, and so on.". Most reviews
+  found online praise the speed, but note that pylint is clearly superior in
+  every other respect.
+
+  * pychecker: it actually *imports* each module (not sure if pylint does this).
+  It seems that pylint = pychecker + coding style and that pylint is more
+  popular.
+
+  * pep8: if all you care is about obeying PEP-8:
+  http://pypi.python.org/pypi/pep8 (includes the actual PEP-8 snippets with the
+  errors found, which is neat). Otherwise, pylint seems like a superset of this. 
+
+  * http://www.doughellmann.com/articles/pythonmagazine/completely-different/2008-03-linters/index.html
+  - article from 2008 comparing pylint, pychecker, and pyflakes. The conclusion
+    is to use pylint, more or less.
+ 
+I say we stick with pylint for now as it provides a great degree of flexibility
+in a single mature package.
+
+  * vim + pylint: http://www.vim.org/scripts/script.php?script_id=891
+  * emcas + pylint: http://www.emacswiki.org/emacs/PythonProgrammingInEmacs#toc5
+
+Automating and enforcing coding style
+-------------------------------------
+
+Ideally, we would like to have a uniform approach to this, where everyone tests
+against the same tool(s) and uses the same list of disabled warnings etc.
+
+Dumi: there are several ways of approaching this, independently of the tools used:
+
+   * Create a precommit hook for mercurial, which runs the tool(s) of choice and
+   generates warnings or aborts the commit process. This hook is a simple Python
+   module (well, as simple as we want it to be), which we can include into
+   everyone's hgrc, in the precommit.pylint variable, for instance. An example
+   is http://github.com/jrburke/dvcs_jslint/blob/master/dvcs_jslint.js. The
+   advantage of this approach is that the load is distributed and
+   errors/warnings are caught client-side, before the commit.
+
+   * Another client-side option is to have editor plugins for the various style
+   checkers: vim and emacs can access pylint pretty easily for instance.
+
+   * Instead of doing this client-side, one can do things server-side. On
+   Assembla, this means using their Webhooks
+   (http://www.assembla.com/spaces/demostuff/webhook_tool), since HTTP-based
+   hooks that we would need to tie with our buildbot server (whichever server we
+   choose that to be).
+
+   * I (DE) prefer starting with the client-side approach, as it is easier to
+   implement, has no single point of failure and is deployable fast. We could
+   have a "batch" script that runs our lint tools in conjunction with hg
+   annotate and sends hate-mail once a week to offenders who have somehow
+   slipped things through the cracks. Also on the server-side we could run
+   time-consuming checking (though how such checks would differ from tests is
+   unclear).
+
+Note that:
+
+  * I haven't found anything ready-made online, so we need to write these
+  hooks ourselves.
+  * I think we should make it so that it is not possible to commit things if
+  pylint reports an actual error.
+
 Type checking
 -------------