Book Image

Python Essentials

By : Steven F. Lott
Book Image

Python Essentials

By: Steven F. Lott

Overview of this book

Table of Contents (22 chapters)
Python Essentials
Credits
About the Author
About the Reviewers
www.PacktPub.com
Preface
Index

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 are calculated using hypotenuse.
    This is the...