Classes are perhaps the most important organizational tool for
Python programming. Python software is often designed as a set of
interacting classes. There are several conventions for naming and
documenting class definitions.
It is important to note that the suite within a class definition
is typically indented four spaces. It is often best to set your text
editor with tab stops every four spaces. This will usually yield the
right kind of layout. Each function's suite is similarly indented four
spaces, as are the suites within compound statements.
Blank lines are used sparingly; most typically a single blank line
will separate each function definition within the class. A lengthy class
definition, with a number of one-liner set-get accessor functions may
group the accessors together without any intervening blank lines.
Class names are typically MixedCase with a leading uppercase
letter. Members of the class (method functions and attributes) typically
begin with a lowercase letter. Class names are also, typically singular
nouns. We don't define
People, we define
Person. A collection might be a PersonList or
Note that the following naming conventions are honored by
single_trailing_underscore_. Used to make a variable names different from a similar Python
reserved word. For example: range_ is a legal variable name.
_single_leading_underscore. Used to make variable or method names hidden. This conceals them
__double_leading_underscore. Class-private names. Use this to assure that a method function
is not used directly by clients of a class.
__double_leading_and_trailing_underscore__. These are essentialy reserved by Python for its own
The first line of a class body is the docstring; this provides an
overview of the class. It should summarize the responsibilities and
collaborators of the class. It should summarize the public methods,
instance variables and particulary the
function used to construct instances of the class. Individual method
functions are each documented in their own docstrings.
When defining a subclass, be sure to mention the specific features
added (or removed) by the subclass. There are two basic cases:
overriding and extending. When overriding a superclass method function,
the subclass has replaced the superclass function. When extending a
superclass function, the subclass method will call the superclass
function to perform some of the work. The override-extend distinctions
must be made clear in the docstring.
When initializing instance variables in the
__init__ function, a string placed after the
assignment statement can serve as a definition of the variable.
class Dice( object ):
"""Model two dice used for craps. Relies on Die class.
theDice -- tuple with two Die instances
Dice() -- initialize two dice
roll() -- roll dice and return total
self.theDice = ( Die(), Die() ) """The two simulated dice."""
"""Roll two dice and return the total."""
map( lambda d: d.roll(), self.theDice )
t = reduce( lambda d: d.face(), self.theDice, 0 )
Generally, we have been omitting a complete docstring header on
each class in the interest of saving some space for the kind of small
examples presented in the text.