Disable quilt.
[mspang/vmailman.git] / STYLEGUIDE.txt
1 Python coding style guide for Mailman
2 Copyright (C) 2002-2004 Barry A. Warsaw
3 $Revision: 7097 $
4
5 NOTE: The canonical version of this style guide can be found at:
6
7     http://barry.warsaw.us/software/STYLEGUIDE.txt
8
9 This document contains a style guide for Python programming, as used in
10 Mailman.  In general, Guido van Rossum's style guide should be taken as a
11 basis, as embodied in PEP 8:
12
13     http://www.python.org/peps/pep-0008.html
14
15 however, my (Barry Warsaw's) personal preferences differ from Guido's in a few
16 places.  "When in Rome..." should apply meaning, when coding stuff for Python,
17 Guido's style should rule, however when coding for Mailman, I'd like to see my
18 preferences used instead.
19
20 Remember rule #1, A Foolish Consistency is the Hobgoblin of Little Minds.
21 That said, here's a quick outline of where my preferences depart from Guido's:
22
23 - Imports usually should be on separate lines.  While it's sometimes
24   okay to say
25
26     from types import StringType, ListType
27
28   it's never okay to say
29
30     import os, sys
31
32   Put these on separate lines.
33
34 - Imports are always put at the top of the file, just after any module
35   comments and docstrings, and before module globals and constants.
36   Imports should be grouped, with the order being:
37
38   1. standard library imports
39   2. related major package imports (i.e. all email package imports next)
40   3. application specific imports
41
42   From-imports should follow non-from imports.  Dotted imports should follow
43   non-dotted imports.  Non-dotted imports should be grouped by increasing
44   length, while dotted imports should be grouped roughly alphabetically.
45
46 - In general, there should be at most one class per module, if the module
47   contains class definitions.  If it's a module of functions, that's fine,
48   group them as common sense dictates.  A class-containing module can also
49   contain some helper functions, but it's best to keep these non-public
50   (i.e. use a single leading underscore).
51
52   Always give the class and the module the same name, differing only by case
53   as PEP 8 recommends.  E.g.
54
55   from mailman.parser import Parser
56
57 - When importing a class from a class-containing module, it's usually
58   okay to spell this
59
60     from myclass import MyClass
61     from foo.bar.yourclass import YourClass
62
63   If this spelling causes name clashes, then spell them
64
65     import myclass
66     import foo.bar.yourclass
67
68   and use "myclass.MyClass"
69
70 - Right hanging comments are discouraged, in favor of preceding comments.
71   E.g.
72
73     foo = blarzigop(bar)  # if you don't blarzigop it, it'll shlorp
74
75   should be written as
76
77     # if you don't blarzigop it, it'll shlorp
78     foo = blarzigop(bar)
79
80 - Major sections of code in a module should be separated by line feed
81   characters (e.g. ^L -- that's a single character control-L not two
82   characters).  This helps with Emacs navigation.
83
84   Always put a ^L before module-level functions, before class definitions,
85   before big blocks of constants which follow imports, and any place else that
86   would be convenient to jump to.  Always put two blank lines before a ^L.
87
88 - Put to blank lines between any module level function.  Put only one blank
89   line between methods in a class.  No blank lines between the class
90   definition and the first method in the class (although class docstrings
91   often go in this space).
92
93 - Try to minimize the vertical whitespace in a class.  If you're inclined to
94   separate stanzas of code for readability, consider putting a comment in
95   describing what the next stanza's purpose is.  Don't put stupid or obvious
96   comments in just to avoid vertical whitespace though.
97
98 - Unless internal quote characters would mess things up, the general rule is
99   that single quotes should be used for short strings, double quotes for
100   triple-quoted multi-line strings and docstrings.  E.g.
101
102     foo = 'a foo thing'
103     warn = "Don't mess things up"
104     notice = """Our three chief weapons are:
105              - surprise
106              - deception
107              - an almost fanatical devotion to the pope
108              """
109
110 - Write docstrings for all public modules, functions, classes, and methods.
111   Docstrings are not necessary and usually discouraged for non-public methods,
112   but you should have a comment that describes what the method does.  This
113   comment should appear after the "def" line.
114
115 - PEP 257 describes good docstrings conventions.  Note that most importantly,
116   the """ that ends a multiline docstring should be on a line by itself, e.g.:
117
118   """Return a foobang
119
120   Optional plotz says to frobnicate the bizbaz first.
121   """
122
123 - For one liner docstrings, keep the closing """ on the same line --
124   except for module docstrings!
125
126 - <> is strongly preferred over !=
127
128 - fill-column for docstrings should be 78.
129
130 - Always use string methods instead of string module functions.
131
132 - For sequences, (strings, lists, tuples), use the fact that empty sequences
133   are false, so "if not seq" or "if seq" is preferable to "if len(seq)" or "if
134   not len(seq)".  Always use True and False instead of 1 and 0 for boolean
135   values.
136
137 - Always decide whether a class's methods and instance variables should be
138   public or non-public.  In general, never make data variables public unless
139   you're implementing essentially a record.  It's almost always preferable to
140   give a functional interface to your class instead (Python 2.2's descriptors
141   and properties make this much nicer).
142
143   Also decide whether your attributes should be private or not.  The
144   difference between private and non-public is that the former will never be
145   useful for a derived class, while the latter might be.  Yes, you should
146   design your classes with inheritance in mind!
147
148 - Single leading underscores are generally preferred for non-public
149   attributes.  Use double leading underscores only in classes designed for
150   inheritance to ensure that truly private attributes will never name clash.
151
152   Public attributes should have no leading or trailing underscores unless they
153   conflict with reserved words, in which case, a single trailing underscore is
154   preferable to a leading one, or a corrupted spelling, e.g. class_ rather
155   than klass.
156
157
158 \f
159 Local Variables:
160 mode: indented-text
161 indent-tabs-mode: nil
162 End: