blob: b307282082ace76bbed0fd6af8ba5cc72cf868fb [file] [log] [blame]
+++++++++++++++++++
Paste Style Guide
+++++++++++++++++++
Generally you should follow the recommendations in `PEP 8`_, the
Python Style Guide. Some things to take particular note of:
.. _PEP 8: http://www.python.org/peps/pep-0008.html
* **No tabs**. Not anywhere. Always indent with 4 spaces.
* I don't stress too much on line length. But try to break lines up
by grouping with parenthesis instead of with backslashes (if you
can). Do asserts like::
assert some_condition(a, b), (
"Some condition failed, %r isn't right!" % a)
* But if you are having problems with line length, maybe you should
just break the expression up into multiple statements.
* Blank lines between methods, unless they are very small and closely
bound to each other.
* Don't use the form ``condition and trueValue or falseValue``. Break
it out and use a variable.
* I (Ian Bicking) am very picky about whitespace. There's one and
only one right way to do it. Good examples::
short = 3
longerVar = 4
if x == 4:
do stuff
func(arg1='a', arg2='b')
func((a + b)*10)
**Bad** examples::
short =3
longerVar=4
if x==4: do stuff
func(arg1 = 'a', arg2 = 'b')
func(a,b)
func( a, b )
[ 1, 2, 3 ]
If the whitespace isn't right, it'll annoy me and I'll feel a need
to fix it. Really, this whitespace stuff shouldn't be that
controversial should it? Some particular points that I feel
strongly about:
* No space after a function name (bad: ``func (arg)``).
* No space after or before a parenthesis (bad: ``func( arg )``).
* Always one space after a comma (bad: ``func(a,b)``).
* Use ``@@`` to mark something that is suboptimal, or where you have a
concern that it's not right. Try to also date it and put your
username there.
* Docstrings are good. They should look like::
class AClass(object):
"""
doc string...
"""
Don't use single quotes (''') -- they tend to cause problems in
Emacs. Don't bother trying make the string less vertically compact.
* Comments go right before the thing they are commenting on.
* Methods never, ever, ever start with capital letters. Generally
only classes are capitalized. But definitely never methods.
* Use ``cls`` to refer to a class. Use ``meta`` to refer to a
metaclass (which also happens to be a class, but calling a metaclass
``cls`` will be confusing).
* Use ``isinstance`` instead of comparing types. E.g.::
if isinstance(var, str): ...
# Bad:
if type(var) is StringType: ...
* Never, ever use two leading underscores. This is annoyingly
private. If name clashes are a concern, use explicit name mangling
instead (e.g., ``_MyThing_blahblah``). This is essentially the same
thing as double-underscore, only it's transparent where double
underscore obscures.
* Module names should be unique in the package. Subpackages shouldn't
share module names with sibling or parent packages. Sadly this
isn't possible for ``__init__.py``, but it's otherwise easy enough.
* Module names should be all lower case, and probably have no
underscores (smushedwords).