pylearn: doc/v2_planning/coding_style.txt comparison

comparison doc/v2_planning/coding_style.txt @ 1155:b70a1fcb7b4f

coding_style: tools to make life easier and automating certain processes

author	Dumitru Erhan <dumitru.erhan@gmail.com>
date	Fri, 17 Sep 2010 16:09:02 +0300
parents	0904dd74894d
children	531e77fb67f2 a0f178bc9052

comparison

equal deleted inserted replaced

-:f923dddf0bf7
+:b70a1fcb7b4f
 * Some random guy guidelines (nothing special): http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
 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
 expression, but sometimes using a backslash looks better.
 --> I rarely find that backslash looks better. In most situations you can
 to use warning instead of logging. (DWF)
 * 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
 covered by tests (see if we can get this from nosetests). Decorator to mark
 some classes / methods as not being tested yet, so as to be able to
 * Standardize the merge commit text (what is the message from fetch?)
 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
 -------------
 (Suggested by Francois Savard)

Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1155:b70a1fcb7b4f