Yueser ← Back to library

AI / Coding and Debugging

Understand unfamiliar code

Explain it by data flow, not line by line

Explain the code below. Requirements: 1) start with one sentence on what it does overall; 2) then follow the data: where the input comes from, what transforms it, where the output goes; 3) flag 2–3 spots that are easiest to misread; 4) point out anything that looks redundant or suspicious. Do not translate the syntax line by line.

```
[paste your code]
```

How to use

Check its data-flow account against the one function in the file you already understand. If that one is wrong, the rest is unreliable.

Good for

You are inheriting someone else's module, or reading the entry file of an undocumented open-source library.
You need to change a piece of code but are unsure where its side effects end, so you want a map of the data flow first.

Not for

The code is scaffold-generated configuration: the official docs are faster than asking a model.
You only need one function's signature: read the type definition or grep for its call sites.

Example

Input

def settle(order, now=None):
    now = now or datetime.utcnow()
    if order.status != "paid" or order.settled_at:
        return None
    amt = order.amount - sum(r.amount for r in order.refunds)
    ledger.post(order.id, amt, at=now)
    order.settled_at = now
    return amt

What you get

Open with one sentence: it posts the net amount (order total minus refunds) of paid, unsettled orders to the ledger. Then follow the flow — status check, net amount, the ledger.post side effect, writing settled_at — and flag that `return None` means both 'should not settle' and 'already settled', and that posting before writing settled_at is not atomic.

Common mistakes

Pasting a 2,000-line file and asking for an explanation: the output degrades into per-section summaries and the data flow breaks at file boundaries.
Pasting only the function body without ledger.post's signature or the order model: the side effects get guessed wrong and the explanation reads well but is unusable.

Try tweaking it like this

Add 'only the part that affects the settlement amount' and the explanation focuses on the path you are about to change.
Ask for 'the call order, with every step that can fail marked' and you get a failure map instead of a description.

More in this topic