Docstrings

Concepts covered: Functions

A function at Uber is read far more often than it is written: by the engineer on call at 3 a.m., by the teammate who wants to reuse it, by the person deciding whether a change is safe. A docstring is a string placed as the first line of the body that explains what the function does, what it expects and what it hands back. Python stores it with the function, which no comment can claim:

def fare_cents(miles, minutes):
    """Return the Uber fare in cents for one trip.

    miles: whole miles driven
    minutes: whole minutes the rider spent in the car
    The fare is 250 plus 175 per mile plus 35 per minute.
    """
    return 250 + miles * 175 + minutes * 35

The 3 double quotes on each end let the string span several lines, which a single quote on each end does not allow. The first line is a one-sentence summary that starts with a verb and ends with a period; a blank line separates it from the details, which name each parameter and say what the return value means, unit included. A closing """ on its own line marks the end.

Python keeps the docstring

A comment is dropped when the program runs. A docstring stays attached to the function, and the built-in help function prints it along with the header. Editors show that same stored docstring as a description when a cursor hovers over a function name:

def fare_cents(miles, minutes):
    """Return the Uber fare in cents for one trip."""
    return 250 + miles * 175 + minutes * 35

help(fare_cents)

Output:

Help on function fare_cents in module __main__:

fare_cents(miles, minutes)
    Return the Uber fare in cents for one trip.

help reports the function's name, its parameters in order, and the docstring under them, with no need to open the body. A one-line docstring like this one fits a function whose parameters explain themselves.

Docstrings and comments

Docstring
  • First statement in the body, in triple quotes
  • Says what the function does, for the people who call it
  • Stored with the function and shown by help()
Comment
  • Any line, starting with #
  • Says why a line is written the way it is, for the people editing the body
  • Dropped when the program runs

Position is the whole test. A triple-quoted string that comes after another statement in the body is an ordinary expression that Python evaluates and discards, so help shows no description for it. The function below contains a string that looks like a docstring:

What does help(tip_cents) show for this function?

def tip_cents(fare):
    rate = 15
    """Return a 15 percent tip in cents."""
    return fare * rate // 100
Do
  • Put the docstring on the line right after the def header
  • Start with a verb: Return, Print, Check
  • Name the unit of every number: cents, miles, minutes
  • Update the docstring in the same edit that changes the behavior
Avoid
  • Restate the code line by line
  • Describe a parameter the function no longer has
  • Use a comment above def for what the function does
  • Write a docstring longer than the body of a 1-line function

Capstone: a documented pricing module

The program below brings the 5 sections together: 3 documented functions, one calling another, used inside a loop that totals a driver's first 3 trips of the week, then a direct call. Predict both printed lines before running it; the trips are 2, 4 and 6 miles, lasting 10, 20 and 30 minutes.

def fare_cents(miles, minutes):
    """Return the fare in cents for one trip."""
    return 250 + miles * 175 + minutes * 35

def tip_cents(fare):
    """Return a 15 percent tip on a fare in cents."""
    return fare * 15 // 100

def trip_total(miles, minutes):
    """Return fare plus tip in cents."""
    fare = fare_cents(miles, minutes)
    return fare + tip_cents(fare)

week = 0
for day in range(1, 4):
    week = week + trip_total(day * 2, day * 10)
print("Week so far:", week)
print(trip_total(8, 25))

Output:

Week so far: 5691
2903

The first trip is 950 cents of fare plus a 142 cent tip, the second 1650 plus 247, the third 2350 plus 352, and the 3 totals sum to 5691. The airport run at 8 miles and 25 minutes is 2525 plus a 378 cent tip. Every number came from one copy of each formula, and help(trip_total) would tell a teammate what the function does without reading a line of its body.

About this lesson

This section is part of the Functions: Beginner lesson on DataDriven, the home of data engineering. Lessons cover SQL, Python, Spark, data modeling and pipeline architecture, and each section pairs its explanation with worked examples and practice you run as you go.