# HG changeset patch # User Dumitru Erhan # Date 1284728942 -10800 # Node ID b70a1fcb7b4f24c0b44845dd5d582e5e08d993ed # Parent f923dddf0bf772f8074883b3cfebc14176e5c111 coding_style: tools to make life easier and automating certain processes diff -r f923dddf0bf7 -r b70a1fcb7b4f doc/v2_planning/coding_style.txt --- 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 -------------