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 PersonSet.

Note that the following naming conventions are honored by Python:

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 from the dir function.

__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 internals.

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 __init__ 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
    """

    def __init__(self):
        self.theDice = ( Die(), Die() ) """The two simulated dice."""

    def roll(self):
        """Roll two dice and return the total."""
        map( lambda d: d.roll(), self.theDice )
        t = reduce( lambda d: d.face(), self.theDice, 0 )
        return t

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.