Python coding style guide for Mailman
Copyright (C) 2002-2009 Barry A. Warsaw

NOTE: The canonical version of this style guide can be found at:

    http://barry.warsaw.us/software/STYLEGUIDE.txt

This document contains a style guide for Python programming, as used in
Mailman.  In general, Guido van Rossum's style guide should be taken as a
basis, as embodied in PEP 8:

    http://www.python.org/peps/pep-0008.html

however, my (Barry Warsaw's) personal preferences differ from Guido's in a few
places.  "When in Rome..." should apply meaning, when coding stuff for Python,
Guido's style should rule, however when coding for Mailman, I'd like to see my
preferences used instead.

Remember rule #1, A Foolish Consistency is the Hobgoblin of Little Minds.
That said, here's a quick outline of where my preferences depart from PEP 8.

- After file comments (e.g. license block), add a __metaclass__ definition so
  that (in Python 2.x) all classes will be new-style.  Following that, add an
  __all__ section that names, one-per-line, all the public names exported by
  this module.

- Imports are always put at the top of the file, just after any module
  comments and docstrings, and before module globals and constants, but after
  any __future__ imports, or __metaclass__ and __all__ definitions.

  Imports should be grouped, with the order being:

  1. standard library imports
  2. related major package imports (e.g. all email package imports next)
  3. application specific imports

  From-imports should follow non-from imports.  Dotted imports should follow
  non-dotted imports.  Non-dotted imports should be grouped by increasing
  length, while dotted imports should be grouped alphabetically.

- In general, there should be at most one class per module, if the module
  contains class definitions.  If it's a module of functions, that's fine,
  group them as common sense dictates.  A class-containing module can also
  contain some helper functions, but it's best to keep these non-public by not
  including them in the __all__ section.

  Give the class and the module the same name, differing only by case as PEP 8
  recommends.  E.g.

  from mailman.parser import Parser

- When importing a class from a class-containing module, it's usually
  okay to spell this

    from myclass import MyClass
    from foo.bar.yourclass import YourClass

  If this spelling causes name clashes, then spell them

    import myclass
    import foo.bar.yourclass

  and use "myclass.MyClass"

  You can also use 'import...as' to rename a clashing symbol.

- Right hanging comments are discouraged, in favor of preceding comments.
  E.g. bad:

    foo = blarzigop(bar)  # if you don't blarzigop it, it'll shlorp

  Good:

    # If you don't blarzigop it, it'll shlorp.
    foo = blarzigop(bar)

  Comments should always be complete sentences, with proper capitalization and
  full stops at the end.

- Major sections of code in a module should be separated by line feed
  characters (e.g. ^L -- that's a single character control-L not two
  characters).  This helps with Emacs navigation.

  Always put a ^L before module-level functions, before class definitions,
  before big blocks of constants which follow imports, and any place else that
  would be convenient to jump to.  Always put two blank lines before a ^L.

- Put two blank lines between any top level construct or block of code
  (e.g. after import blocks).  Put only one blank line between methods in a
  class.  No blank lines between the class definition and the first method in
  the class.  No blank lines between a class/method and its docstrings.

- Try to minimize the vertical whitespace in a class.  If you're inclined to
  separate stanzas of code for readability, consider putting a comment in
  describing what the next stanza's purpose is.  Don't put stupid or obvious
  comments in just to avoid vertical whitespace though.

- Unless internal quote characters would mess things up, the general rule is
  that single quotes should be used for short strings, double quotes for
  triple-quoted multi-line strings and docstrings.  E.g.

    foo = 'a foo thing'
    warn = "Don't mess things up"
    notice = """Our three chief weapons are:
             - surprise
             - deception
             - an almost fanatical devotion to the pope
             """

- Write docstrings for modules, functions, classes, and methods.  Docstrings
  can be omitted for special methods (e.g. __init__() or __str__()) where the
  meaning is obvious.

- PEP 257 describes good docstrings conventions.  Note that most importantly,
  the """ that ends a multiline docstring should be on a line by itself, e.g.:

  """Return a foobang

  Optional plotz says to frobnicate the bizbaz first.
  """

- For one liner docstrings, keep the closing """ on the same line.

- <> is strongly preferred over != (Sadly, Python is making this harder to
  follow and it cannot be followed for Python 3).

- fill-column for docstrings should be 78.

- When testing the emptiness of sequences, use "if len(seq) == 0" instead of
  relying on the falseness of empty sequences.  However, if a variable can be
  one of several false values, it's okay to just use "if seq", though a
  preceding comment is usually in order.

- Always decide whether a class's methods and instance variables should be
  public or non-public.

  Single leading underscores are generally preferred for non-public
  attributes.  Use double leading underscores only in classes designed for
  inheritance to ensure that truly private attributes will never name clash.

  Public attributes should have no leading or trailing underscores unless they
  conflict with reserved words, in which case, a single trailing underscore is
  preferable to a leading one, or a corrupted spelling, e.g. class_ rather
  than klass.



Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: