Write Python functions that explain themselves

Readable code is not only a professional habit. It is also a teaching tool. A well-shaped function lets a learner understand its purpose before they inspect every line.

Start with one clear responsibility

If a function validates input, transforms data, saves a file, and prints a report, its name cannot honestly describe everything it does. Split the workflow into small steps whose names tell the story.

def calculate_average(scores: list[float]) -> float:
    if not scores:
        raise ValueError("scores cannot be empty")
    return sum(scores) / len(scores)

Use type hints as reading aids

• Name the action and the result, not the implementation.
• Use type hints to make inputs and outputs visible.
• Handle invalid input explicitly instead of returning a surprising value.
• Add a docstring when the reason or constraint is not obvious from the code.

These habits scale beyond exercises. They make reviews faster, reduce accidental misuse, and create natural seams for testing.