This commit was manufactured by cvs2svn to create branch

'Release_2_1-maint'.

1 files changed, 165 insertions, 0 deletions

diff --git a/STYLEGUIDE.txt b/STYLEGUIDE.txt
new file mode 100644
index 00000000..2063f9ea
--- /dev/null
+++ b/STYLEGUIDE.txt
@@ -0,0 +1,165 @@
+Python coding style guide for GNU Mailman
+Copyright (C) 2002-2003 Python Software Foundation, Barry A. Warsaw
+
+This document contains a style guide for Python programming, as used
+in GNU Mailman.  In general, Guido van Rossum's style guide should be
+taken as a basis, as embodied in PEP 8:
+
+    http://python.sourceforge.net/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.  For software
+like the email package, which is both standalone and distributed in
+Python's standard library, please adhere to the established style,
+which means please use my style.
+
+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
+
+  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.
+
+  Note though that Zope3's module naming style has a lot of merit.
+  Here, package and module names are all lower cased.  I'm
+  experimenting with this approach for Mailman3.
+
+- 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.
+
+- Also 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, unless
+  your code must work with Python 1.5.2 (but let's hope not).
+
+- 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)".  Unless you must be compatible
+  with Pythons before 2.2.1, 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!
+
+  Private attributes should have two leading underscores, no trailing
+  underscores.
+
+  Non-public attributes should have a single leading underscore, no
+  trailing underscores.
+
+  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).