Update of /cvsroot/mailman/mailman
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22867
Modified Files:
Tag: Release_2_1-maint
STYLEGUIDE.txt
Log Message:
Updates from my online version.
Index: STYLEGUIDE.txt
===================================================================
RCS file: /cvsroot/mailman/mailman/STYLEGUIDE.txt,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -d -r1.1.2.1 -r1.1.2.2
--- STYLEGUIDE.txt 22 Sep 2003 02:54:26 -0000 1.1.2.1
+++ STYLEGUIDE.txt 15 May 2004 22:02:13 -0000 1.1.2.2
@@ -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$
-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 @@
- 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 @@
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 @@
- 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!
- Private attributes should have two leading underscores, no trailing
- underscores.
+- 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.
- 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.
- 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:
_______________________________________________
Mailman-checkins mailing list
[EMAIL PROTECTED]
Unsubscribe: http://mail.python.org/mailman/options/mailman-checkins/archive%40jab.org
