doc/core/development/naming.html

   1 <?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   2   <head>
   3 <title>Twisted Documentation: Naming Conventions</title>
   4 <link href="../howto/stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">Naming Conventions</h1>
   9     <div class="toc"><ol/></div>
  10     <div class="content">
  11
  12 <span/>
  13
  14 <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>
  15
  16 <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>
  17
  18 <p>Here are some examples of this naming scheme:</p>
  19
  20 <ul>
  21 <li>An event notification of data received from peer:
  22 <code class="python">dataReceived(data)</code></li>
  23 <li>A request to send data: <code class="python">write(data)</code></li>
  24 <li>A class that implements a protocol: <code class="python">Protocol</code></li>
  25 </ul>
  26
  27 <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>
  28
  29 <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>
  30
  31 <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>
  32
  33 </div>
  34
  35     <p><a href="../howto/index.html">Index</a></p>
  36     <span class="version">Version: 12.1.0</span>
  37   </body>
  38 </html>