docs/STYLEGUIDE.txt

   1 Python coding style guide for Mailman
   2 Copyright (C) 2002-2007 Barry A. Warsaw
   3 $Revision: 8145 $
   4
   5 NOTE: The canonical version of this style guide can be found at:
   6
   7     http://barry.warsaw.us/software/STYLEGUIDE.txt
   8
   9 This document contains a style guide for Python programming, as used in
  10 Mailman.  In general, Guido van Rossum's style guide should be taken as a
  11 basis, as embodied in PEP 8:
  12
  13     http://www.python.org/peps/pep-0008.html
  14
  15 however, my (Barry Warsaw's) personal preferences differ from Guido's in a few
  16 places.  "When in Rome..." should apply meaning, when coding stuff for Python,
  17 Guido's style should rule, however when coding for Mailman, I'd like to see my
  18 preferences used instead.
  19
  20 Remember rule #1, A Foolish Consistency is the Hobgoblin of Little Minds.
  21 That said, here's a quick outline of where my preferences depart from Guido's:
  22
  23 - Imports usually should be on separate lines.  While it's sometimes
  24   okay to say
  25
  26     from types import StringType, ListType
  27
  28   it's never okay to say
  29
  30     import os, sys
  31
  32   Put these on separate lines.
  33
  34 - Imports are always put at the top of the file, just after any module
  35   comments and docstrings, and before module globals and constants.
  36   Imports should be grouped, with the order being:
  37
  38   1. standard library imports
  39   2. related major package imports (i.e. all email package imports next)
  40   3. application specific imports
  41
  42   From-imports should follow non-from imports.  Dotted imports should follow
  43   non-dotted imports.  Non-dotted imports should be grouped by increasing
  44   length, while dotted imports should be grouped roughly alphabetically.
  45
  46 - In general, there should be at most one class per module, if the module
  47   contains class definitions.  If it's a module of functions, that's fine,
  48   group them as common sense dictates.  A class-containing module can also
  49   contain some helper functions, but it's best to keep these non-public
  50   (i.e. use a single leading underscore).
  51
  52   Always give the class and the module the same name, differing only by case
  53   as PEP 8 recommends.  E.g.
  54
  55   from mailman.parser import Parser
  56
  57 - When importing a class from a class-containing module, it's usually
  58   okay to spell this
  59
  60     from myclass import MyClass
  61     from foo.bar.yourclass import YourClass
  62
  63   If this spelling causes name clashes, then spell them
  64
  65     import myclass
  66     import foo.bar.yourclass
  67
  68   and use "myclass.MyClass"
  69
  70 - Right hanging comments are discouraged, in favor of preceding comments.
  71   E.g.
  72
  73     foo = blarzigop(bar)  # if you don't blarzigop it, it'll shlorp
  74
  75   should be written as
  76
  77     # if you don't blarzigop it, it'll shlorp
  78     foo = blarzigop(bar)
  79
  80 - Major sections of code in a module should be separated by line feed
  81   characters (e.g. ^L -- that's a single character control-L not two
  82   characters).  This helps with Emacs navigation.
  83
  84   Always put a ^L before module-level functions, before class definitions,
  85   before big blocks of constants which follow imports, and any place else that
  86   would be convenient to jump to.  Always put two blank lines before a ^L.
  87
  88 - Put to blank lines between any module level function.  Put only one blank
  89   line between methods in a class.  No blank lines between the class
  90   definition and the first method in the class (although class docstrings
  91   often go in this space).
  92
  93 - Try to minimize the vertical whitespace in a class.  If you're inclined to
  94   separate stanzas of code for readability, consider putting a comment in
  95   describing what the next stanza's purpose is.  Don't put stupid or obvious
  96   comments in just to avoid vertical whitespace though.
  97
  98 - Unless internal quote characters would mess things up, the general rule is
  99   that single quotes should be used for short strings, double quotes for
 100   triple-quoted multi-line strings and docstrings.  E.g.
 101
 102     foo = 'a foo thing'
 103     warn = "Don't mess things up"
 104     notice = """Our three chief weapons are:
 105              - surprise
 106              - deception
 107              - an almost fanatical devotion to the pope
 108              """
 109
 110 - Write docstrings for all public modules, functions, classes, and methods.
 111   Docstrings are not necessary and usually discouraged for non-public methods,
 112   but you should have a comment that describes what the method does.  This
 113   comment should appear after the "def" line.
 114
 115 - PEP 257 describes good docstrings conventions.  Note that most importantly,
 116   the """ that ends a multiline docstring should be on a line by itself, e.g.:
 117
 118   """Return a foobang
 119
 120   Optional plotz says to frobnicate the bizbaz first.
 121   """
 122
 123 - For one liner docstrings, keep the closing """ on the same line --
 124   except for module docstrings!
 125
 126 - <> is strongly preferred over !=
 127
 128 - fill-column for docstrings should be 78.
 129
 130 - Always use string methods instead of string module functions.
 131
 132 - For sequences, (strings, lists, tuples), use the fact that empty sequences
 133   are false, so "if not seq" or "if seq" is preferable to "if len(seq)" or "if
 134   not len(seq)".  Always use True and False instead of 1 and 0 for boolean
 135   values.
 136
 137 - Always decide whether a class's methods and instance variables should be
 138   public or non-public.  In general, never make data variables public unless
 139   you're implementing essentially a record.  It's almost always preferable to
 140   give a functional interface to your class instead (Python 2.2's descriptors
 141   and properties make this much nicer).
 142
 143   Also decide whether your attributes should be private or not.  The
 144   difference between private and non-public is that the former will never be
 145   useful for a derived class, while the latter might be.  Yes, you should
 146   design your classes with inheritance in mind!
 147
 148 - Single leading underscores are generally preferred for non-public
 149   attributes.  Use double leading underscores only in classes designed for
 150   inheritance to ensure that truly private attributes will never name clash.
 151
 152   Public attributes should have no leading or trailing underscores unless they
 153   conflict with reserved words, in which case, a single trailing underscore is
 154   preferable to a leading one, or a corrupted spelling, e.g. class_ rather
 155   than klass.
 156
 157
 158 \f
 159 Local Variables:
 160 mode: indented-text
 161 indent-tabs-mode: nil
 162 End: