Readable code and refactoring

Pure logic, side effects at the edges

A pocket calculator is the model here. The same keys give the same answer, and pressing them changes nothing else in the world. A pure function works like that: it returns a result that depends only on its inputs, and changes nothing outside itself. round(19.99 * 0.85, 2) is pure. A side effect is anything else: printing, writing a file, calling an API, changing a global variable, reading the clock.

Programs need side effects, or they'd do nothing useful. But mixing them into your logic makes the logic hard to test and hard to reuse. Think of a restaurant, where cooks cook and waiters deal with the guests. A good shape is a functional core of pure functions, wrapped in a thin shell that does the input and output:

# Core: pure and easy to test.
def overdue_invoices(invoices, today):
    return [inv for inv in invoices if inv["due"] < today and not inv["paid"]]

def reminder_text(invoice):
    return f"Invoice {invoice['id']} for {invoice['amount']} was due on {invoice['due']}."

# Shell: does the I/O (here, print stands in for sending email).
invoices = [
    {"id": "A1", "amount": 120, "due": "2026-09-01", "paid": False},
    {"id": "A2", "amount": 80, "due": "2026-12-01", "paid": False},
    {"id": "A3", "amount": 45, "due": "2026-08-15", "paid": True},
]
for inv in overdue_invoices(invoices, today="2026-10-30"):
    print(reminder_text(inv))

Notice today is passed in rather than read from the clock. That one choice makes the function testable on any date.

Comments say why, not what

i += 1              # add one to i            <- says what the code already says
retries += 1        # the payment API often fails once on cold start, so we allow one retry

The first comment is noise. The second records something the code can't: the reason. If code needs a comment to explain what it does, try renaming or splitting it first.

In plain words: let names say what the code does, and comments say why it does it that way.

Refactoring: change the shape, keep the behavior

Tidying a garage doesn't change what you own. It only makes things easier to find. Refactoring means improving code's structure without changing what it does. The rule that makes it safe: small steps, tests green after each one. Rename one thing, run the tests. Pull out one function, run the tests. If a test fails, the last small step is the culprit.

Common refactorings:

• Rename a variable or function to say what it is.
• Extract a function from a block that does one identifiable job.
• Replace a magic number with a named constant.
• Use guard clauses: handle the special cases first and return early, so the main logic isn't buried under layers of if.

Code smells

A faint smell of gas doesn't prove a leak, but you'd go and check. A code smell isn't a bug either. It's a sign that a bug, or a painful change, is likely:

Don't remove duplication too early. Two similar blocks may drift apart for good reasons. Many engineers follow the rule of three: extract on the third copy, when the pattern is clear.

Formatters and linters handle the mechanical part, the way a spell-checker does. Ruff and Black are the common Python tools. A formatter fixes spacing and layout so nobody argues about it. A linter flags likely mistakes, like unused imports or variables that are never defined.

def can_refund_nested(order, days_since):
    if order["paid"]:
        if not order["refunded"]:
            if days_since <= 30:
                return True
            else:
                return False
        else:
            return False
    else:
        return False

REFUND_WINDOW_DAYS = 30

def can_refund(order, days_since):
    if not order["paid"]:
        return False
    if order["refunded"]:
        return False
    return days_since <= REFUND_WINDOW_DAYS

cases = [({"paid": True, "refunded": False}, 10), ({"paid": True, "refunded": True}, 3),
         ({"paid": False, "refunded": False}, 1), ({"paid": True, "refunded": False}, 45)]
print([can_refund_nested(o, d) for o, d in cases])
print([can_refund(o, d) for o, d in cases])

Judgment calls

Short names don't save time. You type a name once and read it dozens of times. n is fine in a three-line loop, but customers_without_orders is better for anything you'll meet again later. And if you feel a comment is needed to explain what a block does, try renaming or splitting it first.

Don't refactor and add features together. You wouldn't rewire a house while you paint it. If you change the shape of the code and its behavior in one go, then a failing test can't tell you which part broke it. Refactor first with the tests green, and commit. Then add the feature. It feels slower, and it's usually faster.

Not all duplication is bad. Two blocks that look alike today may need to change for different reasons tomorrow. Merge them too early, and you end up with one function full of flags and special cases, which is worse than the copies. A useful rule is to wait until you have three real examples before you pull out a shared function. Duplication is cheaper than the wrong abstraction.

The next reader

The person reading your code next may well be you, months from now, with none of today's context. Leave them what you'd want to find.