~msapiro/mailman/topics

Python coding style guide for Mailman

Copyright (C) 2002-2004 Barry A. Warsaw

$Revision: 7097 $

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/dev/peps/pep-0008/

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 Guido's:

- Imports usually should be on separate lines.  While it's sometimes

  okay to say

    from types import StringType, ListType

  it's never okay to say

    import os, sys

  Put these on separate lines.

- Imports are always put at the top of the file, just after any module

  comments and docstrings, and before module globals and constants.

  Imports should be grouped, with the order being:

  1. standard library imports

  2. related major package imports (i.e. 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 roughly 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

  (i.e. use a single leading underscore).

  Always 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"

- Right hanging comments are discouraged, in favor of preceding comments.

  E.g.

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

  should be written as

    # if you don't blarzigop it, it'll shlorp

    foo = blarzigop(bar)

- 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 to blank lines between any module level function.  Put only one blank

  line between methods in a class.  No blank lines between the class

  definition and the first method in the class (although class docstrings

  often go in this space).

- 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 all public modules, functions, classes, and methods.

  Docstrings are not necessary and usually discouraged for non-public methods,

  but you should have a comment that describes what the method does.  This

  comment should appear after the "def" line.

- 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 --

  except for module docstrings!

- <> is strongly preferred over !=

- fill-column for docstrings should be 78.

- Always use string methods instead of string module functions.

- For sequences, (strings, lists, tuples), use the fact that empty sequences

  are false, so "if not seq" or "if seq" is preferable to "if len(seq)" or "if

  not len(seq)".  Always use True and False instead of 1 and 0 for boolean

  values.

- Always decide whether a class's methods and instance variables should be

  public or non-public.  In general, never make data variables public unless

  you're implementing essentially a record.  It's almost always preferable to

  give a functional interface to your class instead (Python 2.2's descriptors

  and properties make this much nicer).

  Also decide whether your attributes should be private or not.  The

  difference between private and non-public is that the former will never be

  useful for a derived class, while the latter might be.  Yes, you should

  design your classes with inheritance in mind!

- 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: