Paste Style Guide

Generally you should follow the recommendations in PEP 8, the Python Style Guide. Some things to take particular note of:

  • 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).