Mercurial > pylearn
diff doc/v2_planning/coding_style.txt @ 1060:b4ccf6b43f27
coding_style: Added some comments about PEP8
author | Olivier Delalleau <delallea@iro> |
---|---|
date | Thu, 09 Sep 2010 12:01:49 -0400 |
parents | 573363a9b5c7 |
children | 64720cdca3d3 |
line wrap: on
line diff
--- a/doc/v2_planning/coding_style.txt Wed Sep 08 20:45:17 2010 -0400 +++ b/doc/v2_planning/coding_style.txt Thu Sep 09 12:01:49 2010 -0400 @@ -12,6 +12,7 @@ ---------------------------------------------------------- * http://www.python.org/dev/peps/pep-0008/ + * http://www.python.org/dev/peps/pep-0257/ * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html * http://www.voidspace.org.uk/python/articles/python_style_guide.shtml * http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html @@ -31,6 +32,64 @@ Dumi: we should also try to find tools that automate these processes: pylint, pyflakes, pychecker, pythontidy +OD: I think PEP8 + Google guidelines are a good basis. +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 + get rid of them. Typically I prefer: + if (cond_1 and + cond_2 and + cond_3): + to + if cond_1 and \ + cond_2 and \ + cond_3: + + * You should use two spaces after a sentence-ending period. + --> Looks weird to me. + + * Imports should usually be on separate lines + --> Can be a lot of lines wasted for no obvious benefit. I think this is + mostly useful when you import different modules from different places, + but I would say that for instance for standard modules it would be + better to import them all on a single line (doing multiple lines only + if there are too many of them), e.g. prefer: + import os, sys, time + to + import os + import sys + import time + However, I agree about separating imports between standard lib / 3rd + party, e.g. prefer: + import os, sys, time + import numpy, scipy + to + import numpy, os, scipy, sys, time + (Personal note: preferably order imports by alphabetical order, makes + it easier to quickly see if a specific module is already imported, + and avoids duplicated imports) + + * Missing in PEP 8: + - How to indent multi-line statements? E.g. do we want + x = my_func(a, b, c, + d, e, f) + or + x = my_func(a, b, c, + d, e, f) + or + x = my_func( + a, b, c, d, e, f) + --> Probably depends on the specific situation, but we could have a + few typical examples (and the same happens with multi-lines lists) + + * From PEP 257: The BDFL [3] recommends inserting a blank line between the + last paragraph in a multi-line docstring and its closing quotes, placing + the closing quotes on a line by themselves. This way, Emacs' + fill-paragraph command can be used on it. + --> I have nothing against Emacs, but this is ugly! + Documentation ------------- @@ -52,5 +111,5 @@ Meetings -------- -Next meeting: Thursday 2010/09/09, 11 am + * Thursday 2010/09/09, 11 am