← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/vision/naming.xhtml

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2004-06-21 22:01:11 UTC
  • mto: (2.2.3 sid)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20040621220111-vkf909euqnyrp3nr
Tags: upstream-1.3.0
Import upstream version 1.3.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/vision/naming.xhtml
 
1
<html xmlns="http://www.w3.org/1999/xhtml">
 
2
<head>
 
3
<title>Naming Conventions</title>
 
4
</head>
 
5
<body>
 
6
 
 
7
<h1>Naming Conventions</h1>
 
8
 
 
9
<p>While this may sound like a small detail, clear method naming is important to provide an API that developers familiar with event-based programming can pick up quickly.</p>
 
10
 
 
11
<p>Since the idea of a method call maps very neatly onto that of a received event, all event handlers are simply methods named after past-tense verbs. All class names are descriptive nouns, designed to mirror the is-a relationship of the abstractions they implement. All requests for notification or transmission are present-tense imperative verbs.</p>
 
12
 
 
13
<p>Here are some examples of this naming scheme:</p>
 
14
 
 
15
<ul>
 
16
<li>An event notification of data received from peer:
 
17
<code class="python">dataReceived(data)</code></li>
 
18
<li>A request to send data: <code class="python">write(data)</code></li>
 
19
<li>A class that implements a protocol: <code class="python">Protocol</code></li>
 
20
</ul>
 
21
 
 
22
<p>The naming is platform neutral. This means that the names are equally appropriate in a wide variety of environments, as long as they can publish the required events.</p>
 
23
 
 
24
<p>It is self-consistent. Things that deal with TCP use the acronym TCP, and it is always capitalized. Dropping, losing, terminating, and closing the connection are all referred to as <q>losing</q> the connection. This symmetrical naming allows developers to easily locate other API calls if they have learned a few related to what they want to do.</p>
 
25
 
 
26
<p>It is semantically clear. The semantics of dataReceived are simple: there are some bytes available for processing. This remains true even if the lower-level machinery to get the data is highly complex.</p>
 
27
 
 
28
</body>
 
29
</html>