Name and Document the Interface

Use meaningful function and parameter names, write concise docstrings about caller-visible behavior, and reserve comments for hidden reasons.

A caller should be able to understand a function before reading every line of its body. The function name, parameter names, and docstring describe that boundary.

Name the Result, Not the Mechanism

Compare these names:

loop_values(items) describes one implementation step. mean(readings) names the result the caller asks for.

The parameter readings also explains what the input means better than a generic name such as data or x in this small program.

Names do not need to repeat every detail. They should let a call read as a clear operation:

Q1. Choose the caller-facing name

Which name best describes a function that returns the mean of available readings?

Choose one

mean(readings)

loop_and_add(values)

do_work(x)

Select one choice, then check.

HintRead it as a caller

The caller needs a mean, not a loop.

SolutionName the requested result

mean(readings) tells the caller what is returned and what values are used.

State the Behavior in a Docstring

A docstring is a string placed as the first statement in a function body:

This sentence records what a caller may rely on:

the function returns a mean;
unavailable readings do not enter it;
the special result is None when no reading is available.

It does not narrate each assignment or restate the loop. Those details are already visible in the body and may change without changing the interface.

Q2. Choose the useful docstring

Which docstring gives the caller the most useful contract?

Choose one

Return the mean of available readings, or None when none are available.

Set total to zero, loop, add, count, and divide.

Do a calculation.

Select one choice, then check.

HintDescribe what remains stable

The loop could change while the documented result stays the same.

SolutionDocument behavior and the boundary

The contract sentence explains the returned value and the None case without duplicating the implementation.

Use a Comment Only When It Adds a Reason

A docstring belongs to the function interface. A comment inside the body explains a local choice that the code alone does not make clear:

The comment explains the meaning of the skip. Comments such as # Add reading to total merely repeat total += reading and can be removed.

Q3. Write the interface contract

Add a concise docstring to format_mean that states its returned text and the None case.

Editable Python

HintPlace documentation first

Begin the body with a triple-quoted sentence that states the returned text and the None case, before the if statement.

SolutionState both outcomes

A clear interface combines meaningful names, a short behavior-focused docstring, and comments only where a reason is otherwise hidden. The chapter now has a reusable, tested, and documented measurement program. Chapter 5 will give these functions richer ordered data to select and transform.