1 files changed, 162 insertions, 0 deletions
diff --git a/docs/STYLEGUIDE.txt b/docs/STYLEGUIDE.txt
new file mode 100644
index 000000000..1cdca7c4e
--- /dev/null
+++ b/docs/STYLEGUIDE.txt
@@ -0,0 +1,162 @@
+Python coding style guide for Mailman
+Copyright (C) 2002-2004 Barry A. Warsaw
+$Revision: 8143 $
+
+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 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: