~certify-web-dev/twisted/certify-trunk

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Twisted Coding Standard</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Twisted Coding Standard</h1><div class="toc"><ol><li><a href="#auto0">Naming</a></li><li><a href="#auto1">Testing</a></li><li><a href="#auto2">Whitespace</a></li><li><a href="#auto3">Modules</a></li><li><a href="#auto4">Packages</a></li><li><a href="#auto5">Docstrings</a></li><li><a href="#auto6">Scripts</a></li><li><a href="#auto7">Standard Library Extension Modules</a></li><li><a href="#auto8">ChangeLog</a></li><li><a href="#auto9">Classes</a></li><li><a href="#auto10">Methods</a></li><li><a href="#auto11">Callback Arguments</a></li><li><a href="#auto12">Special Methods</a></li><li><a href="#auto13">Functions</a></li><li><a href="#auto14">Attributes</a></li><li><a href="#auto15">Database</a></li><li><a href="#auto16">C Code</a></li><li><a href="#auto17">Commit Messages</a></li><li><a href="#auto18">Source Control</a></li><li><a href="#auto19">Recommendations</a></li></ol></div><div class="content"><h2>Naming<a name="auto0"></a></h2>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.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

something.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. <h2>Testing<a name="auto1"></a></h2>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.html"><code>test-case-name</code></a> tags that

point to their related tests.Acceptance tests are all automated by the admin/accepttests

script currently. (TODO: real acceptance tests strategy!)Run the unit tests tests before you check anything in.Let me repeat that, for emphasis: run the unit tests before you

check anything in. 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 SVN commit privileges.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.If you modify, or write a new, HOWTO, please read the <a href="http://twistedmatrix.com/projects/lore">Lore</a>

documentation to learn the format the docs.<h2>Whitespace<a name="auto2"></a></h2>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.Lines are flowed at 79 columns.<h2>Modules<a name="auto3"></a></h2>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.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.Depending on the situation, it is acceptable to have imports that

look like this:

from twisted.internet.defer import Deferred

</pre>

or like this:

from twisted.internet import defer

</pre>

That is, modules should import modules or classes and

functions, but not packages.Wildcard import syntax may not be used by code in Twisted. These

imports lead to code which is difficult to read and maintain by

introducing complexity which strains human readers and automated tools

alike. If you find yourself with many imports to make from a single

module and wish to save typing, consider importing the module itself,

rather than its attributes.Relative imports (or sibling imports) may not be

used by code in Twisted. Relative imports allow certain circularities

to be introduced which can ultimately lead to unimportable modules or

duplicate instances of a single module. Relative imports also make the

task of refactoring more difficult.<h2>Packages<a name="auto4"></a></h2>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.<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.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,<pre class="python">

# parent/

# --- __init__.py ---

import child

# --- child.py ---

import parent

class Foo:

pass

parent.Foo = Foo

</pre>Every package should be added to the list in

<code class="shell">setup.py</code>.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.<h2>Docstrings<a name="auto5"></a></h2>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, an 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.Docstrings are never 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).Docstrings should be indented to the level of the code they

are documenting.Docstrings should be triple-quoted.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>.Additionally, to accommodate emacs users:<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

100

string.</li><li>Code examples in docstrings should be prefixed by the |

101

character. This will prevent IM-Python from regarding sample

102

code as real functions, methods, and classes.</li></ul>For example,<pre class="python">

103

def foo2bar(f):

104

"""I am a function to convert foos to bars.

105

106

I should be used when you have a foo but you want a bar; note that this is

107

a non-destructive operation. If I can\'t convert the foo to a bar I will

108

raise a FooException().

109

110

For example::

111

112

| import wombat

113

| def sample(something):

114

| f = something.getFoo()

115

| f.doFooThing()

116

| b = wombat.foo2bar(f)

117

| b.doBarThing()

118

| return b

119

120

"""

121

# Optionally, actual code can go here.

122

</pre><h2>Scripts<a name="auto6"></a></h2>For each <q>script</q>, that is, a program you expect a Twisted user

123

to run from the command-line, the following things must be done:<ol><li>Write a module in <code class="API">twisted.scripts</code>

124

which contains a callable global named <code>run</code>. This

125

will be called by the command line part with no arguments (it

126

will usually read <code>sys.argv</code>). Feel free to write more

127

functions or classes in this module, if you feel they are useful

128

to others.</li><li>Write a file in <code class="shell">bin/</code> which contains the

129

Twisted running-from-SVN header, and ending with

130

131

132

from twisted.scripts.yourmodule import run

133

run()

134

</pre></li><li>Write a manpage in <code class="shell">doc/man</code>.

135

On debian systems you can find a skeleton example of a manpage in

136

<code>/usr/share/doc/man-db/examples/manpage.example</code>.</li><li>Add your script to the script list in

137

<code class="shell">setup.py</code>.</li></ol>This will insure your program will work correctly for users of SVN,

138

Windows releases and Debian packages.<h2>Standard Library Extension Modules<a name="auto7"></a></h2>When using the extension version of a module for which there is also

139

a Python version, place the import statement inside a try/except block,

140

and import the Python version if the import fails. This allows code to

141

work on platforms where the extension version is not available. For

142

example:

143

144

145

try:

146

import cPickle as pickle

147

except ImportError:

148

import pickle

149

</pre>

150

151

Use the "as" syntax of the import statement as well, to set

152

the name of the extension module to the name of the Python module.<h2>ChangeLog<a name="auto8"></a></h2>All changes that will affect the way end-users see Twisted should come

153

with an appropriate entry in the ChangeLog that summarizes that impact.The correct format for the ChangeLog is GNU changelog format. There is

154

an emacs mode for editing this, use <code>M-x add-change-log-entry</code>.

155

If you are, for whatever absurd reason, using an editor other than emacs

156

to edit Twisted, you can use Moshe Zadka's helpfully provided

157

<code>admin/change</code> script to add a properly-formatted entry.<h2>Classes<a name="auto9"></a></h2>Classes are to be named in mixed case, with the first letter

158

capitalized; each word separated by having its first letter

159

capitalized. Acronyms should be capitalized in their entirety.

160

Class names should not be prefixed with the name of the module they are

161

in. Examples of classes meeting this criteria:<ul><li>twisted.spread.pb.ViewPoint</li><li>twisted.parser.patterns.Pattern</li></ul>Examples of classes not meeting this criteria:<ul><li>event.EventHandler</li><li>main.MainGadget</li></ul>An effort should be made to prevent class names from clashing

162

with each other between modules, to reduce the need for

163

qualification when importing. For example, a Service subclass

164

for Forums might be named twisted.forum.service.ForumService,

165

and a Service subclass for Words might be

166

twisted.words.service.WordsService. Since neither of these

167

modules are volatile (see above) the classes may be

168

imported directly into the user's namespace and not cause

169

confusion.<h2>Methods<a name="auto10"></a></h2>Methods should be in mixed case, with the first letter lower

170

case, each word separated by having its first letter

171

capitalized. For example, <code>someMethodName</code>,

172

<code>method</code>.Sometimes, a class will dispatch to a specialized sort of

173

method using its name; for example, twisted.reflect.Accessor.

174

In those cases, the type of method should be a prefix in all

175

lower-case with a trailing underscore, so method names will

176

have an underscore in them. For example, <code>get_someAttribute</code>.

177

Underscores in method names in twisted code are therefore

178

expected to have some semantic associated with them.Some methods, in particular <code>addCallback</code> and its

179

cousins return self to allow for chaining calls. In this case,

180

wrap the chain in parenthesis, and start each chained call on

181

a separate line, for example:<pre class="python">

182

return (foo()

183

.addCallback(bar)

184

.addCallback(thud)

185

.addCallback(wozers))

186

</pre><h2>Callback Arguments<a name="auto11"></a></h2>There are several methods whose purpose is to help the user set up

187

callback functions, for example <code base="twisted.internet.defer" class="API">Deferred.addCallback</code> or the

188

reactor's <code base="twisted.internet.base.ReactorBase" class="API">callLater</code> method. To make

189

access to the callback as transparent as possible, most of these methods

190

use <code class="python">**kwargs</code> to capture arbitrary arguments

191

that are destined for the user's callback. This allows the call to the

192

setup function to look very much like the eventual call to the target

193

callback function.In these methods, take care to not have other argument names that will

194

<q>steal</q> the user's callback's arguments. When sensible, prefix these

195

<q>internal</q> argument names with an underscore. For example, <code base="twisted.spread.pb" class="API">RemoteReference.callRemote</code> is

196

meant to be called like this:<pre class="python">

197

myref.callRemote("addUser", "bob", "555-1212")

198

199

# on the remote end, the following method is invoked:

200

def addUser(name, phone):

201

...

202

</pre>where <q>addUser</q> is the remote method name. The user might also

203

choose to call it with named parameters like this:<pre class="python">

204

myref.callRemote("addUser", name="bob", phone="555-1212")

205

</pre>In this case, <code>callRemote</code> (and any code that uses the

206

**kwargs syntax) must be careful to not use <q>name</q>, <q>phone</q>, or

207

any other name that might overlap with a user-provided named parameter.

208

Therefore, <code>callRemote</code> is implemented with the following

209

signature:<pre class="python">

210

def callRemote(self, _name, *args, **kw):

211

...

212

</pre>Do whatever you can to reduce user confusion. It may also be

213

appropriate to <code class="python">assert</code> that the kwargs

214

dictionary does not contain parameters with names that will eventually

215

cause problems.<h2>Special Methods<a name="auto12"></a></h2>The augmented assignment protocol, defined by __iadd__ and other

216

similarly named methods, can be used to allow objects to be modified in

217

place or to rebind names if an object is immutable -- both through use

218

of the same operator. This can lead to confusing code, which in turn

219

leads to buggy code. For this reason, methods of the augmented

220

assignment protocol should not be used in Twisted.<h2>Functions<a name="auto13"></a></h2>Functions should be named similiarly to methods.Functions or methods which are responding to events to

221

complete a callback or errback should be named <code>_cbMethodName</code> or

222

<code>_ebMethodName</code>, in order to distinguish them from normal

223

methods.<h2>Attributes<a name="auto14"></a></h2>Attributes should be named similarly to functions and

224

methods. Attributes should be named descriptively; attribute

225

names like <code>mode</code>, <code>type</code>, and

226

<code>buf</code> are generally discouraged. Instead, use

227

<code>displayMode</code>, <code>playerType</code>, or

228

<code>inputBuffer</code>.Do not use Python's <q>private</q> attribute syntax; prefix

229

non-public attributes with a single leading underscore. Since

230

several classes have the same name in Twisted, and they are

231

distinguished by which package they come from, Python's

232

double-underscore name mangling will not work reliably in some

233

cases. Also, name-mangled private variables are more difficult

234

to address when unit testing or persisting a class.An attribute (or function, method or class) should be

235

considered private when one or more of the following conditions

236

are true:<ul><li>The attribute represents intermediate state which is not

237

always kept up-to-date.</li><li>Referring to the contents of the attribute or otherwise

238

maintaining a reference to it may cause resources to

239

leak.</li><li>Assigning to the attribute will break internal

240

assumptions.</li><li>The attribute is part of a known-to-be-sub-optimal

241

interface and will certainly be removed in a future

242

release.</li></ul><h2>Database<a name="auto15"></a></h2>Database tables will be named with plural nouns.Database columns will be named with underscores between

243

words, all lower case, since most databases do not distinguish

244

between case.Any attribute, method argument, or method name that

245

corresponds directly to a column in the database will

246

be named exactly the same as that column, regardless of other

247

coding conventions surrounding that circumstance.All SQL keywords should be in upper case.<h2>C Code<a name="auto16"></a></h2>Wherever possible, C code should be optional, and the

248

default python implementation should be maintained in tandem

249

with it. C code should be strict ANSI C, and

250

must build using GCC as well as Visual Studio

251

for Windows, and really shouldn't have any problems with other

252

compilers either. Don't do anything tricky.C code should only be used for efficiency, not for binding

253

to external libraries. If your particular code is not

254

frequently run, write it in Python. If you require the use of

255

an external library, develop a separate, external bindings

256

package and make your twisted code depend on it.<h2>Commit Messages<a name="auto17"></a></h2>The commit messages are being distributed in a myriad of ways. Because

257

of that, you need to observe a few simple rules when writing a commit

258

message.The first line of the message is being used as both the subject of

259

the commit email and the announcement on #twisted. Therefore, it should

260

be short (aim for < 80 characters) and descriptive -- and must be

261

able to stand alone (it is best if it is a complete sentence). The rest

262

of the e-mail should be separated with hard line breaks into

263

short lines (< 70 characters). This is free-format, so you can do

264

whatever you like here.Commit messages should be about what, not how: we can

265

get how from SVN diff. Explain reasons for commits, and what they

266

affect.Each commit should be a single logical change, which is internally

267

consistent. If you can't summarize your changes in one short line, this

268

is probably a sign that they should be broken into multiple checkins.<h2>Source Control<a name="auto18"></a></h2>Twisted currently uses Subversion for source control. All

269

development should occur using branches; when a task is

270

considered complete another Twisted developer may review it and if no

271

problems are found, it may be merged into trunk (TODO: Describe this

272

more thoroughly (Divmod wiki has <a href="http://divmod.org/trac/wiki/BranchBasedDevelopment">a start</a>)).

273

Branches must be used for major development. Branches

274

should be managed using <a href="http://divmod.org/trac/wiki/DivmodCombinator">Combinator</a> (but

275

if you can manage them in some other way without anyone noticing, knock

276

yourself out).Certain features of Subversion should be avoided.<ul><li>Do not set the <code class="shell">svn:ignore</code> property on any

277

file or directory. What you wish to ignore, others may wish to examine.

278

What others may wish you ignore, you may wish you examine.

279

<code class="shell"> svn:ignore </code> will affect everyone who uses

280

the repository, and so it is not the right mechanism to express personal

281

preferences.If you wish to ignore certain files use the <code class="shell">

282

global-ignores </code> feature of <code class="shell">

283

~/.subversion/config </code>, for example:<pre class="shell">

284

[miscellany]

285

global-ignores = dropin.cache *.pyc *.pyo *.o *.lo *.la #*# .*.rej *.rej .*~

286

</pre></li></ul><h2>Recommendations<a name="auto19"></a></h2>These things aren't necessarily standardizeable (in that

287

code can't be easily checked for compliance) but are a good

288

idea to keep in mind while working on Twisted.If you're going to work on a fragment of the Twisted

289

codebase, please consider finding a way that you would use

290

such a fragment in daily life. I use the Twisted Web server on

291

the main TML website, and aside from being good PR, this

292

encourages you to actively maintain and improve your code, as

293

the little everyday issues with using it become apparent.Twisted is a big codebase! If you're

294

refactoring something, please make sure to recursively grep for

295

the names of functions you're changing. You may be surprised to

296

learn where something is called. Especially if you are moving

297

or renaming a function, class, method, or module, make sure

298

that it won't instantly break other code.</div><a href="../howto/index.html">Index</a>Version: 2.5.0</body></html>

b'\\ No newline at end of file'

Older »