Advanced

Style that reads years from now

A function looks fine today. Two years from now, when you're the one trying to fix it, it won't. Style isn't about decoration -- it's about leaving the code easier to read than you found it. AI review is useful here because it has no loyalty to the way you currently wrote it.

What you will see

Function sizes (lines of code): big_mixed: 42 calculate_total: 6 apply_discount: 6 save_cart: 6 Each split function does one thing: True

About 2 min of reading

Try It

Renaming and splitting functions for readability

Give functions and variables clear names that explain their purpose.

unclear = { "f": "returns total price", "x": "current user cart", "calc": "compute discount", } print() print("Style: naming and split") for short, meaning in unclear.items(): print("Rename '%s' -> clearer name for: %s" % (short, meaning))

Before you run it, say out loud what it will print. Then open the answer.

What it prints

Style: naming and split Rename 'f' -> clearer name for: returns total price Rename 'x' -> clearer name for: current user cart Rename 'calc' -> clearer name for: compute discount

Split a big mixed function into small single-purpose functions.

def big_mixed(): for i in range(100): pass return 0 def calculate_total(cart): return 0 def apply_discount(total, rate): return 0 def save_cart(cart): return 0 print("Function sizes (lines of code):") print("big_mixed: %d" % len(big_mixed.__code__.co_code)) print("calculate_total: %d" % len(calculate_total.__code__.co_code)) print("apply_discount: %d" % len(apply_discount.__code__.co_code)) print("save_cart: %d" % len(save_cart.__code__.co_code)) print("Each split function does one thing: True")

Before you run it, say out loud what it will print. Then open the answer.

What it prints

Function sizes (lines of code): big_mixed: 42 calculate_total: 6 apply_discount: 6 save_cart: 6 Each split function does one thing: True

Data Flow

Ask for a style cleanup, rename the unclear parts, split long functions, and read through once more.

1 Ask for a cleanup

↓

2 Rename the unclear parts

↓

3 Split long functions

↓

4 Read it again

Why this works

Clear names first

Ask "what names are unclear?" Good names remove most of the need for comments -- if the name explains the action, you don't need a sentence under it.

Keep functions small

Ask "can this be split?" Small functions are easy to test, easy to review, and easy to reuse. A function that does one thing is a function that ages well.

Examples

Renaming x1 and x2

You: "Clean up this function."
AI: "Rename x1 and x2 to clear names. Split the 60-line function in two."

def x1(x2):   # nothing about this tells you what it does
    ...

The renamed version reads almost like a sentence, and suddenly the 60-line function feels manageable split into two. The rename was the small change; the follow-through on the split is what made it maintainable.

The dead code nobody removed

You: "Clean up this file."
AI: "Two unused functions and a commented-out block. Remove them."

# def old_calc(x):   # replaced by new_calc months ago
#     return x * 2

Dead code isn't just clutter -- it's a distraction. A new reader has to figure out whether that commented function matters, and now they're tripping over your history. Removing it keeps the file honest and makes the next review faster.

Comments that argue with the code

You: "Which comments can I remove?"
AI: "This one says 'add items' but the code subtracts. Delete it or fix it."

total += price   # add items to total

A comment that disagrees with the code is worse than no comment, because it lies to the next person. When the code and the words fight, someone is confused in a few months. Ask the AI to flag every comment that doesn't match what's actually happening.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Finding the slow parts instead of guessing

Previous Lesson

Finding the slow parts instead of guessing

Next Lesson

How much a review is worth is set by the prompt

How much a review is worth is set by the prompt →