Writing docstrings

In Chapter 7, Basic Function Definitions, we noted that all functions should have a docstring that describes the function. In Chapter 11, Class Definitions, and Chapter 12, Scripts, Modules, Packages, Libraries, and Applications, we offered similar advice, without providing many details.

The def statement and the class statement should, universally, be followed by a triple-quoted string that describes the function, method, or class. It's not required by the language—it's required by all of the people who will try to read, understand, extend, improve, or repair our code.

We'll revisit an example from Chapter 11, Class Definitions, to show the kinds of docstrings that were omitted. Here's how we might create a more complete class definition:

class Point:
    """
    Point on a plane.

    Distances are calculated using hypotenuse.
    This is the "as a crow flies" straight line distance.

    Point on a plane.

    Distances...