1 +++++++++++++++++++ 2 Paste Style Guide 3 +++++++++++++++++++ 4 5 Generally you should follow the recommendations in `PEP 8`_, the 6 Python 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
