StyleGuide.txt 3.1 KB

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