1+++++++++++++++++++
2Paste Style Guide
3+++++++++++++++++++
4
5Generally you should follow the recommendations in `PEP 8`_, the
6Python Style Guide.  Some things to take particular note of:
7
8.. _PEP 8: http://www.python.org/peps/pep-0008.html
9
10* **No tabs**.  Not anywhere.  Always indent with 4 spaces.
11
12* I don't stress too much on line length.  But try to break lines up
13  by grouping with parenthesis instead of with backslashes (if you
14  can).  Do asserts like::
15
16    assert some_condition(a, b), (
17        "Some condition failed, %r isn't right!" % a)
18
19* But if you are having problems with line length, maybe you should
20  just break the expression up into multiple statements.
21
22* Blank lines between methods, unless they are very small and closely
23  bound to each other.
24
25* Don't use the form ``condition and trueValue or falseValue``.  Break
26  it out and use a variable.
27
28* I (Ian Bicking) am very picky about whitespace.  There's one and
29  only one right way to do it.  Good examples::
30
31    short = 3
32    longerVar = 4
33
34    if x == 4:
35        do stuff
36
37    func(arg1='a', arg2='b')
38    func((a + b)*10)
39
40  **Bad** examples::
41
42    short    =3
43    longerVar=4
44
45    if x==4: do stuff
46
47    func(arg1 = 'a', arg2 = 'b')
48    func(a,b)
49    func( a, b )
50    [ 1, 2, 3 ]
51
52  If the whitespace isn't right, it'll annoy me and I'll feel a need
53  to fix it.  Really, this whitespace stuff shouldn't be that
54  controversial should it?  Some particular points that I feel
55  strongly about:
56
57  * No space after a function name (bad: ``func (arg)``).
58  * No space after or before  a parenthesis (bad: ``func( arg )``).
59  * Always one space after a comma (bad: ``func(a,b)``).
60
61* Use ``@@`` to mark something that is suboptimal, or where you have a
62  concern that it's not right.  Try to also date it and put your
63  username there.
64
65* Docstrings are good.  They should look like::
66
67    class AClass(object):
68        """
69        doc string...
70        """
71
72  Don't use single quotes (''') -- they tend to cause problems in
73  Emacs.  Don't bother trying make the string less vertically compact.
74
75* Comments go right before the thing they are commenting on.
76
77* Methods never, ever, ever start with capital letters.  Generally
78  only classes are capitalized.  But definitely never methods.
79
80* Use ``cls`` to refer to a class.  Use ``meta`` to refer to a
81  metaclass (which also happens to be a class, but calling a metaclass
82  ``cls`` will be confusing).
83
84* Use ``isinstance`` instead of comparing types.  E.g.::
85
86    if isinstance(var, str): ...
87    # Bad:
88    if type(var) is StringType: ...
89
90* Never, ever use two leading underscores.  This is annoyingly
91  private.  If name clashes are a concern, use explicit name mangling
92  instead (e.g., ``_MyThing_blahblah``).  This is essentially the same
93  thing as double-underscore, only it's transparent where double
94  underscore obscures.
95
96* Module names should be unique in the package.  Subpackages shouldn't
97  share module names with sibling or parent packages.  Sadly this
98  isn't possible for ``__init__.py``, but it's otherwise easy enough.
99
100* Module names should be all lower case, and probably have no
101  underscores (smushedwords).
102
103