Phase 5: Object-Oriented & Modular Thinking · ~30 minutes · Python · uv

Writing Code Other People (and Future You) Can Read

Fewer lines isn't better code. Code is read far more often than it's written, and a clever one-liner charges every future reader interest on the five seconds you saved writing it.

Hiring signal: Chooses clarity over cleverness by default, and can explain the real cost of a dense one-liner in a code review

What you will learn

Choose names that reveal intent instead of requiring the reader to decode them
Distinguish what docstrings and comments are each actually for
Recognize function/class size and 'clever' density as real maintainability smells, not style nitpicks
Judge which of two equivalent implementations a stranger could safely modify

Introduction

Type: Learn Languages: Python Prerequisites: Lesson 03 (Composition and Modular Design) Time: ~30 minutes

Objective

Learning objectives

Choose names that reveal intent instead of requiring the reader to decode them
Distinguish what docstrings and comments are each actually for
Recognize function/class size and "clever" density as real maintainability smells, not style nitpicks
Judge which of two equivalent implementations a stranger could safely modify

What you're building

Take this working-but-badly-named script:

def f(l):
    r = []
    for i in l:
        if i['s'] == 'active':
            r.append(i['n'])
    return r

data = [
    {"n": "Ada", "s": "active"},
    {"n": "Grace", "s": "inactive"},
    {"n": "Alan", "s": "active"},
]
print(f(data))

A script (readable_refactor.py) that:

Renames every function, parameter, and variable to reveal its actual purpose (what does f do? what is l? what do "s" and "n" represent?)
Adds one docstring describing the function's interface, and at most one comment explaining anything genuinely non-obvious (there may not be anything worth a comment here — that's a valid outcome, not a failure)
Verifies, by running both versions, that the renamed version produces identical output to the original for the same input data
Contains a comment briefly explaining what specifically made the original version harder to understand

Two functions compute the same result. Version A is one dense line combining a filter, a sort, and a transformation. Version B is eight lines, each doing exactly one of those three steps in order. A new team member needs to add a fourth step. Which version can they modify with the least risk of breaking something they didn't intend to touch?

This is the direct, general version of this lesson's comprehension-vs-loop example. 'Less code to read' is not the same claim as 'easier to safely change' — Version A's density means understanding it well enough to extend requires holding the filter, sort, and transformation all in your head simultaneously, and a mistake in reconstructing that dense expression can silently break a step you never meant to touch. Version B's isolation means the new team member can add their fourth step in its own new spot without needing to fully re-derive the other three first.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers The Problem, Check Yourself, Key Terms & Next — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.