3
<title>Twisted Coding Standard</title>
7
<h1>Twisted Coding Standard</h1>
10
Try to choose names which are both easy to remember and meaningful.
11
Some silliness is OK at the module naming level (see twisted.spread...)
12
but when choosing class names, be as precise as possible. Write code
13
with a dictionary and thesaurus open on the table next to you.
16
Try to avoid overloaded terms. This rule is often broken, since it is
17
incredibly difficult, as most normal words have already been taken by
18
some other software. More importantly, try to avoid meaningless words.
19
In particular, words like "handler", "processor", "engine", "manager",
20
and "component" don't really indicate what something does, only that it
21
does <b>something</b>.
25
Unit tests are written using the PyUnit framework. Many examples are
26
in the twisted.test package, and all tests should be integrated through
27
the main test suite builder in twisted.test.test_all.
30
Acceptance tests are all automated by the bin/accepttests script
31
currently. (TODO: real acceptance tests strategy!)
35
Indentation is 4 spaces per indent. Tabs are not allowed. It is
36
preferred that every block appear on a new line, so that control
37
structure indentation is always visible.
41
Modules must be named in all lower-case, preferably short, single
42
words. If a module name contains multiple words, they may be separated
43
by underscores or not separated at all.
46
In most cases, modules should contain more than one class, function, or
47
method; if a module contains only one object, consider refactoring to
48
include more related functionality in that module.
51
<em>Note that this rule is a change from previous versions of Twisted,
52
so a lot of code does not yet adhere to it.</em>
55
By default, objects from modules in Twisted ought to be imported
56
directly into the namespace of the module that uses them, like this:
57
<code>from twisted.python.defer import Deferred</code>
60
In some cases, however, Twisted takes advantage of the dynamic binding
61
of Python in order to provide an interface through a module that may be
62
imported -- we call these "volatile" modules, because their internals
63
are subject to change without warning. In these cases, it is
64
desireable to import the module itself into the user's namespace, so
65
that things bound to it will be looked up on each call. For obvious
66
reasons, classes in volatile modules should never be subclassed.
69
Volatile modules will have a __volatile__ attribute set to 1, and
70
should always have a docstring snippet like the one that follows:
75
NOTE: this is a __volatile__ module. This means that if you are using it
76
externally, you should know that its contents may change at any time. In
77
general, all this means is that you must not use it like this::
79
from twisted.package.module import Class
82
but instead like this::
84
from twisted.package import module
92
Package names should follow the same conventions as module names. All
93
modules must be encapsulated in some package. Nested packages may be
94
used to further organize related modules.
97
__init__.py must never contain anything other than a docstring and
98
(optionally) an __all__ attribute. Packages are not modules and should
99
be treated differently. This rule may be broken to preserve backwards
100
compatibility if a module is made into a nested package as part of a
104
If you wish to promote code from a module to a package, for
105
example, to break a large module out into several smaller
106
files, the accepted way to do this is to promote from within
107
the module. For example,
110
# --- __init__.py ---
123
Wherever possible, docstrings should be used to describe the purpose of
124
methods, functions, classes, and modules. In cases where it's
125
desirable to avoid documenting thoroughly -- for example, and evolving
126
interface -- insert a placeholder docstring ("UNDOCUMENTED" is
127
preferred), so that the auto-generated API documentation will not pick
128
up an extraneous comment as the documentation for that
129
module/class/function.
132
Docstrings are <em>never</em> to be used to provide semantic
133
information about an object; this rule may be violated if the code in
134
question is to be used in a system where this is a requirement (such as
138
Docstrings should be indented to the level of the code they are
142
Docstrings should be triple-quoted.
145
Docstrings should be written in StructuredText format; more
146
documentation is available on the <a
147
href="http://happydoc.sourceforge.net">HappyDoc website</a>.
150
Additionally, to accommodate emacs users:
154
Single quotes of the type of the docstring's triple-quote should be
155
escaped. This will prevent font-lock from accidentally fontifying
156
large portions of the file as a string.
159
Code examples in docstrings should be prefixed by the | character.
160
This will prevent IM-Python from regarding sample code as real
161
functions, methods, and classes.
169
"""I am a function to convert foos to bars.
171
I should be used when you have a foo but you want a bar; note that this is a
172
non-destructive operation. If I can\'t convert the foo to a bar I will raise a
178
| def sample(something):
179
| f = something.getFoo()
181
| b = wombat.foo2bar(f)
186
# Optionally, actual code can go here.
192
Classes are to be named in mixed case, with the first letter
193
capitalized; each word separated by having its first letter
194
capitalized. Acronyms should be capitalized in their entirety. Class
195
names should not include the name of the module they are a part of.
198
<li> twisted.reality.thing.Thing </li>
199
<li> twisted.web.Handler </li>
200
<li> twisted.spread.pb.ViewPoint </li>
201
<li> twisted.parser.patterns.Pattern </li>
203
An effort should be made to prevent class names from clashing with each
204
other between modules, to reduce the need for qualification when
205
importing. For example, a Service subclass for Forums might be named
206
twisted.forum.service.ForumService, and a Service subclass for Words
207
might be twisted.words.service.WordsService. Since neither of these
208
modules are volatile <i>(see above)</i> the classes may be imported
209
directly into the user's namespace and not cause confusion.
214
Methods should be in mixed case, with the first letter lower case, each
215
word separated by having its first letter capitalized. For example,
216
"someMethodName", "method".
219
Sometimes, a class will dispatch to a specialized sort of method using
220
its name; for example, twisted.reflect.Accessor. In those cases, the
221
type of method should be a prefix in all lower-case with a trailing
222
underscore, so method names will have an underscore in them. For
223
example, "get_someAttribute". Underscores in method names in twisted
224
code are therefore expected to have some semantic associated with them.
229
Functions should be named similiarly to methods.
233
Attributes should be named similarly to functions and methods.
234
Attributes should be named descriptively; attribute names like
235
<code>mode</code>, <code>type</code>, and <code>buf</code> are
236
generally discouraged. Instead, use <code>displayMode</code>,
237
<code>playerType</code>, or <code>inputBuffer</code>.
240
Do not use Python's "private" attribute syntax; prefix non-public
241
attributes with a single leading underscore. Since several classes
242
have the same name in Twisted, and they are distinguished by which
243
package they come from, Python's double-underscore name mangling will
244
not work reliably in some cases. Also, name-mangled private variables
245
are more difficult to address when unit testing or persisting a class.
248
An attribute (or function, method or class) should be considered private
249
when one or more of the following conditions are true:
251
<li>The attribute represents intermediate state which is not always
252
kept up-to-date.</li>
254
<li>Referring to the contents of the attribute or otherwise
255
maintaining a reference to it may cause resources to leak.</li>
257
<li>Assigning to the attribute will break internal assumptions.</li>
259
<li>The attribute is part of a known-to-be-sub-optimal interface and
260
will certainly be removed in a future release.</li>
265
Database tables will be named with plural nouns.
268
Database columns will be named with underscores between words, all
269
lower case, since most databases do not distinguish between case.
272
Any attribute, method argument, or method name that corresponds
273
<em>directly</em> to a column in the database will be named exactly the
274
same as that column, regardless of other coding conventions surrounding
278
All SQL keywords should be in upper case.
282
Wherever possible, C code should be optional, and the default python
283
implementation should be maintained in tandem with it. C code should
284
be strict ANSI C, and <strong>must</strong> build using GCC as well as
285
Visual Studio for Windows, and really shouldn't have any problems with
286
other compilers either. Don't do anything tricky.
289
C code should only be used for efficiency, not for binding to external
290
libraries. If your particular code is not frequently run, write it in
291
Python. If you require the use of an external library, develop a
292
separate, external bindings package and make your twisted code depend
295
<h3>Recommendations</h3>
297
These things aren't necessarily standardizeable (in that code can't be
298
easily checked for compliance) but are a good idea to keep in mind
299
while working on Twisted.
302
If you're going to work on a fragment of the Twisted codebase, please
303
consider finding a way that you would *use* such a fragment in daily
304
life. I use the Twisted Web server on the main TML website, and aside
305
from being good PR, this encourages you to actively maintain and
306
improve your code, as the little everyday issues with using it become
310
Twisted is a <strong>big</strong> codebase! If you're refactoring
311
something, please make sure to recursively grep for the names of
312
functions you're changing. You may be surprised to learn where
313
something is called. Especially if you are moving or renaming a
314
function, class, method, or module, make sure that it won't instantly
318
<address><a href="mailto:glyph@helix.twistedmatrix.com">Glyph Lefkowitz</a></address>
319
<!-- Created: Thu Apr 26 07:53:26 CDT 2001 -->
321
Last modified: Fri Jan 25 18:04:28 CST 2002
added
removed
doc/CodingStandard.html
