diff options
| -rw-r--r-- | STYLEGUIDE.txt | 175 |
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: |