Updates from my online version.

1 files changed, 86 insertions, 89 deletions

diff --git a/STYLEGUIDE.txt b/STYLEGUIDE.txt
index 2063f9ea..16663c90 100644
--- a/STYLEGUIDE.txt
+++ b/STYLEGUIDE.txt
@@ -1,23 +1,24 @@
-Python coding style guide for GNU Mailman
-Copyright (C) 2002-2003 Python Software Foundation, Barry A. Warsaw
+Python coding style guide for Mailman
+Copyright (C) 2002-2004 Barry A. Warsaw
+$Revision: 7097 $
 
-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:
+NOTE: The canonical version of this style guide can be found at:
 
-    http://python.sourceforge.net/peps/pep-0008.html
+    http://barry.warsaw.us/software/STYLEGUIDE.txt
 
-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.
+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:
 
-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:
+    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
@@ -32,44 +33,42 @@ depart from Guido's:
 
 - 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
+  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.
+  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).
+- 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.
+  Always give the class and the module the same name, differing only by case
+  as PEP 8 recommends.  E.g.
 
-  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.
+  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
+    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
+    import myclass
+    import foo.bar.yourclass
 
-  and use "MyClass.MyClass"
+  and use "myclass.MyClass"
 
-- Right hanging comments are discouraged, in favor of preceding
-  comments.  E.g.
+- Right hanging comments are discouraged, in favor of preceding comments.
+  E.g.
 
     foo = blarzigop(bar)  # if you don't blarzigop it, it'll shlorp
 
@@ -82,43 +81,39 @@ depart from Guido's:
   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.
+  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).
+- 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.
+- 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.
+- 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
-	     """
+             - 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.
+- 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.:
+- 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
 
@@ -132,34 +127,36 @@ depart from Guido's:
 
 - 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).
+- 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)".  Unless you must be compatible
-  with Pythons before 2.2.1, always use True and False instead of 1
-  and 0 for boolean values.
+- 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).
+- 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!
+  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.
 
-  Private attributes should have two leading underscores, 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.
 
-  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).
+
+Local Variables:
+mode: indented-text
+indent-tabs-mode: nil
+End: