coding-standard.xhtml [plain text]
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Twisted Coding Standard</title>
</head>
<body>
<h1>Twisted Coding Standard</h1>
<h2>Naming</h2>
<p>Try to choose names which are both easy to remember and
meaningful. Some silliness is OK at the module naming level
(see <code class="API">twisted.spread</code>...) but when
choosing class names, be as precise as possible. Write code
with a dictionary and thesaurus open on the table next to
you.</p>
<p>Try to avoid overloaded terms. This rule is often broken,
since it is incredibly difficult, as most normal words have
already been taken by some other software. More importantly,
try to avoid meaningless words. In particular, words like
<q>handler</q>, <q>processor</q>, <q>engine</q>, <q>manager</q>
and <q>component</q> don't really indicate what something does,
only that it does
<em>something</em>.</p>
<p>Use American spelling in both names and docstrings. For compound
technical terms such as 'filesystem', use a non-hyphenated spelling in
both docstrings and code in order to avoid unnecessary
capitalization. </p>
<h2>Testing</h2>
<p>Unit tests are written using the <code
class="API">twisted.trial</code> framework. Many examples are in the
<code class="API">twisted.test</code> package. Test modules should start
with 'test_' in their name. Source files should have <a
href="test-standard.xhtml"><code>test-case-name</code></a> tags that
point to their related tests.</p>
<p>Acceptance tests are all automated by the admin/accepttests
script currently. (TODO: real acceptance tests strategy!)</p>
<p>Run the unit tests tests before you check anything in.</p>
<p>Let me repeat that, for emphasis: <em>run the unit tests before you
check <strong>anything</strong> in</em>. Code which breaks
functionality is unfortunate and unavoidable. The acceptance tests
are highly nonportable and sometimes a pain to run, so this is pardonable.
Code which breaks the unit tests in a way that you could have prevented
by running them yourself, however, may be grounds for anything from
merciless taunting through revertion of the breakage to revocation
of cvs commit privileges.</p>
<p>It is strongly suggested that developers learn to use Emacs, and use
the <code>twisted-dev.el</code> file included in the TwistedEmacs
package to bind the F9 key to <q>run unit tests</q> and bang on it
frequently. Support for other editors is unavailable at this time
but we would love to provide it.</p>
<p>If you modify, or write a new, HOWTO, please read the <a
href="../lore.xhtml">Lore documentation</a> to learn the format the docs.</p>
<h2>Whitespace</h2>
<p>Indentation is 4 spaces per indent. Tabs are not allowed. It
is preferred that every block appear on a new line, so that
control structure indentation is always visible.</p>
<h2>Modules</h2>
<p>Modules must be named in all lower-case, preferably short,
single words. If a module name contains multiple words, they
may be separated by underscores or not separated at all.</p>
<p>In most cases, modules should contain more than one class,
function, or method; if a module contains only one object,
consider refactoring to include more related functionality in
that module.</p>
<p>Depending on the situation, it is acceptable to have imports that
look like this:
<pre class="python">from twisted.internet.defer import Deferred</pre>
or like this:
<pre class="python">from twisted.internet import defer</pre>
That is, modules should import <em>modules</em> or
<em>classes and functions</em>, but not <em>packages</em>.</p>
<h2>Packages</h2>
<p>Package names should follow the same conventions as module
names. All modules must be encapsulated in some package. Nested
packages may be used to further organize related modules.</p>
<p><code>__init__.py</code> must never contain anything other than a
docstring and (optionally) an <code>__all__</code> attribute. Packages are
not modules and should be treated differently. This rule may be
broken to preserve backwards compatibility if a module is made
into a nested package as part of a refactoring.</p>
<p>If you wish to promote code from a module to a package, for
example, to break a large module out into several smaller
files, the accepted way to do this is to promote from within
the module. For example,</p>
<pre class="python">
# parent/
# --- __init__.py ---
import child
# --- child.py ---
import parent
class Foo:
pass
parent.Foo = Foo
</pre>
<p>Every package should be added to the list in
<code class="shell">setup.py</code>.</p>
<p>Packages must not depend circularly upon each other. To simplify
maintaining this state, packages must also not import each other
circularly. While this applies to all packages within Twisted, one
<code>twisted.python</code> deserves particular attention, as it may
not depend on any other Twisted package.</p>
<h2>Docstrings</h2>
<p>Wherever possible, docstrings should be used to describe the
purpose of methods, functions, classes, and modules. In cases
where it's desirable to avoid documenting thoroughly -- for
example, and evolving interface -- insert a placeholder
docstring (<code class="py-src-string">"UNDOCUMENTED"</code> is preferred),
so that the
auto-generated API documentation will not pick up an extraneous
comment as the documentation for that
module/class/function.</p>
<p>Docstrings are <em>never</em> to be used to provide semantic
information about an object; this rule may be violated if the
code in question is to be used in a system where this is a
requirement (such as Zope).</p>
<p>Docstrings should be indented to the level of the code they
are documenting.</p>
<p>Docstrings should be triple-quoted.</p>
<p>Docstrings should be written in epytext format; more
documentation is available in the
<a href="http://epydoc.sourceforge.net/epytext.html"
>Epytext Markup Language documentation</a>.</p>
<p>Additionally, to accommodate emacs users:</p>
<ul>
<li>Single quotes of the type of the docstring's triple-quote
should be escaped. This will prevent font-lock from
accidentally fontifying large portions of the file as a
string.</li>
<li>Code examples in docstrings should be prefixed by the |
character. This will prevent IM-Python from regarding sample
code as real functions, methods, and classes.</li>
</ul>
<p>For example,</p>
<pre class="python">
def foo2bar(f):
"""I am a function to convert foos to bars.
I should be used when you have a foo but you want a bar; note that this is
a non-destructive operation. If I can\'t convert the foo to a bar I will
raise a FooException().
For example::
| import wombat
| def sample(something):
| f = something.getFoo()
| f.doFooThing()
| b = wombat.foo2bar(f)
| b.doBarThing()
| return b
"""
# Optionally, actual code can go here.
</pre>
<h2>Scripts</h2>
<p>For each <q>script</q>, that is, a program you expect a Twisted user
to run from the command-line, the following things must be done:</p>
<ol>
<li>Write a module in <code class="API">twisted.scripts</code>
which contains a callable global named <code>run</code>. This
will be called by the command line part with no arguments (it
will usually read <code>sys.argv</code>). Feel free to write more
functions or classes in this module, if you feel they are useful
to others.</li>
<li>Write a file in <code class="shell">bin/</code> which contains the
Twisted running-from-CVS header, and ending with
<pre class="python">
from twisted.scripts.yourmodule import run
run()
</pre></li>
<li>Write a manpage in <code class="shell">doc/man</code>.
On debian systems you can find a skeleton example of a manpage in
<code>/usr/share/doc/man-db/examples/manpage.example</code>.</li>
<li>Add your script to the script list in
<code class="shell">setup.py</code>.</li>
</ol>
<p>This will insure your program will work correctly for users of CVS,
Windows releases and Debian packages.</p>
<h2>Standard Library Extension Modules</h2>
<p>When using the extension version of a module for which there is also
a Python version, place the import statement inside a try/except block,
and import the Python version if the import fails. This allows code to
work on platforms where the extension version is not available. For
example:
<pre class="python">
try:
import cPickle as pickle
except ImportError:
import pickle
</pre>
Use the "as" syntax of the import statement as well, to set
the name of the extension module to the name of the Python module.</p>
<h2>ChangeLog</h2>
<p>All changes that will affect the way end-users see Twisted should come
with an appropriate entry in the ChangeLog that summarizes that impact.</p>
<p>The correct format for the ChangeLog is GNU changelog format. There is
an emacs mode for editing this, use <code>M-x add-change-log-entry</code>.
If you are, for whatever absurd reason, using an editor other than emacs
to edit Twisted, you can use Moshe Zadka's helpfully provided
<code>admin/change</code> script to add a properly-formatted entry.</p>
<h2>Classes</h2>
<p>Classes are to be named in mixed case, with the first letter
capitalized; each word separated by having its first letter
capitalized. Acronyms should be capitalized in their entirety.
Class names should not be prefixed with the name of the module they are
in. Examples of classes meeting this criteria:</p>
<ul>
<li>twisted.spread.pb.ViewPoint</li>
<li>twisted.parser.patterns.Pattern</li>
</ul>
<p>Examples of classes <strong>not</strong> meeting this criteria:</p>
<ul>
<li>event.EventHandler</li>
<li>main.MainGadget</li>
</ul>
<p>An effort should be made to prevent class names from clashing
with each other between modules, to reduce the need for
qualification when importing. For example, a Service subclass
for Forums might be named twisted.forum.service.ForumService,
and a Service subclass for Words might be
twisted.words.service.WordsService. Since neither of these
modules are volatile <em>(see above)</em> the classes may be
imported directly into the user's namespace and not cause
confusion.</p>
<h2>Methods</h2>
<p>Methods should be in mixed case, with the first letter lower
case, each word separated by having its first letter
capitalized. For example, <code>someMethodName</code>,
<code>method</code>.</p>
<p>Sometimes, a class will dispatch to a specialized sort of
method using its name; for example, twisted.reflect.Accessor.
In those cases, the type of method should be a prefix in all
lower-case with a trailing underscore, so method names will
have an underscore in them. For example, <code>get_someAttribute</code>.
Underscores in method names in twisted code are therefore
expected to have some semantic associated with them.</p>
<p>Some methods, in particular <code>addCallback</code> and its
cousins return self to allow for chaining calls. In this case,
wrap the chain in parenthesis, and start each chained call on
a separate line, for example:</p>
<pre class="python">
return (foo()
.addCallback(bar)
.addCallback(thud)
.addCallback(wozers))
</pre>
<h2>Callback Arguments</h2>
<p>There are several methods whose purpose is to help the user set up
callback functions, for example <code class="API"
base="twisted.internet.defer">Deferred.addCallback</code> or the
reactor's <code class="API"
base="twisted.internet.base.ReactorBase">callLater</code> method. To make
access to the callback as transparent as possible, most of these methods
use <code class="python">**kwargs</code> to capture arbitrary arguments
that are destined for the user's callback. This allows the call to the
setup function to look very much like the eventual call to the target
callback function.</p>
<p>In these methods, take care to not have other argument names that will
<q>steal</q> the user's callback's arguments. When sensible, prefix these
<q>internal</q> argument names with an underscore. For example, <code
class="API" base="twisted.spread.pb">RemoteReference.callRemote</code> is
meant to be called like this:</p>
<pre class="python">
myref.callRemote("addUser", "bob", "555-1212")
# on the remote end, the following method is invoked:
def addUser(name, phone):
...
</pre>
<p>where <q>addUser</q> is the remote method name. The user might also
choose to call it with named parameters like this:</p>
<pre class="python">
myref.callRemote("addUser", name="bob", phone="555-1212")
</pre>
<p>In this case, <code>callRemote</code> (and any code that uses the
**kwargs syntax) must be careful to not use <q>name</q>, <q>phone</q>, or
any other name that might overlap with a user-provided named parameter.
Therefore, <code>callRemote</code> is implemented with the following
signature:</p>
<pre class="python">
def callRemote(self, _name, *args, **kw):
...
</pre>
<p>Do whatever you can to reduce user confusion. It may also be
appropriate to <code class="python">assert</code> that the kwargs
dictionary does not contain parameters with names that will eventually
cause problems.</p>
<h2>Special Methods</h2>
<p>The augmented assignment protocol, defined by __iadd__ and other
similarly named methods, can be used to allow objects to be modified in
place or to rebind names if an object is immutable -- both through use
of the same operator. This can lead to confusing code, which in turn
leads to buggy code. For this reason, methods of the augmented
assignment protocol should not be used in Twisted.</p>
<h2>Functions</h2>
<p>Functions should be named similiarly to methods.</p>
<p>Functions or methods which are responding to events to
complete a callback or errback should be named <code>_cbMethodName</code> or
<code>_ebMethodName</code>, in order to distinguish them from normal
methods.</p>
<h2>Attributes</h2>
<p>Attributes should be named similarly to functions and
methods. Attributes should be named descriptively; attribute
names like <code>mode</code>, <code>type</code>, and
<code>buf</code> are generally discouraged. Instead, use
<code>displayMode</code>, <code>playerType</code>, or
<code>inputBuffer</code>.</p>
<p>Do not use Python's <q>private</q> attribute syntax; prefix
non-public attributes with a single leading underscore. Since
several classes have the same name in Twisted, and they are
distinguished by which package they come from, Python's
double-underscore name mangling will not work reliably in some
cases. Also, name-mangled private variables are more difficult
to address when unit testing or persisting a class.</p>
<p>An attribute (or function, method or class) should be
considered private when one or more of the following conditions
are true:</p>
<ul>
<li>The attribute represents intermediate state which is not
always kept up-to-date.</li>
<li>Referring to the contents of the attribute or otherwise
maintaining a reference to it may cause resources to
leak.</li>
<li>Assigning to the attribute will break internal
assumptions.</li>
<li>The attribute is part of a known-to-be-sub-optimal
interface and will certainly be removed in a future
release.</li>
</ul>
<h2>Database</h2>
<p>Database tables will be named with plural nouns.</p>
<p>Database columns will be named with underscores between
words, all lower case, since most databases do not distinguish
between case.</p>
<p>Any attribute, method argument, or method name that
corresponds <em>directly</em> to a column in the database will
be named exactly the same as that column, regardless of other
coding conventions surrounding that circumstance.</p>
<p>All SQL keywords should be in upper case.</p>
<h2>C Code</h2>
<p>Wherever possible, C code should be optional, and the
default python implementation should be maintained in tandem
with it. C code should be strict ANSI C, and
<strong>must</strong> build using GCC as well as Visual Studio
for Windows, and really shouldn't have any problems with other
compilers either. Don't do anything tricky.</p>
<p>C code should only be used for efficiency, not for binding
to external libraries. If your particular code is not
frequently run, write it in Python. If you require the use of
an external library, develop a separate, external bindings
package and make your twisted code depend on it.</p>
<h2>Checkin Messages</h2>
<p>Thanks to CVSToys, the checkin messages are being used in a myriad
of ways. Because of that, you need to observe a few simple rules when
writing a checkin message.</p>
<p>The first line of the message is being used as both the subject of
the commit e-mail and the announcement on #twisted. Therefore, it should
be short (aim for < 80 characters) and descriptive -- and must be
able to stand alone (it is best if it is a complete sentence). The rest
of the e-mail should be separated with <em>hard line breaks</em> into
short lines (< 70 characters). This is free-format, so you can do
whatever you like here.</p>
<p>Checkin messages should be about <em>what</em>, not <em>how</em>: we
can get how from CVS diff. Explain reasons for checkins, and what they
affect.</p>
<p>Each commit should be a single logical change, which is internally
consistent. If you can't summarize your changes in one short line, this
is probably a sign that they should be broken into multiple checkins.</p>
<h2>Recommendations</h2>
<p>These things aren't necessarily standardizeable (in that
code can't be easily checked for compliance) but are a good
idea to keep in mind while working on Twisted.</p>
<p>If you're going to work on a fragment of the Twisted
codebase, please consider finding a way that you would <em>use</em>
such a fragment in daily life. I use the Twisted Web server on
the main TML website, and aside from being good PR, this
encourages you to actively maintain and improve your code, as
the little everyday issues with using it become apparent.</p>
<p>Twisted is a <strong>big</strong> codebase! If you're
refactoring something, please make sure to recursively grep for
the names of functions you're changing. You may be surprised to
learn where something is called. Especially if you are moving
or renaming a function, class, method, or module, make sure
that it won't instantly break other code.</p>
</body>
</html>