A team inherits a module nobody can read: one-letter arguments, magic numbers, no comments, forty lines of nested branches. They rewrite it cleanly in an afternoon. The new version is shorter, readable and passes review. Nothing fails. The service runs for weeks with no complaint. Then a season changes, or a month rolls over, and a whole category of records starts coming out wrong — promised dates too early, discounts too small, penalties charged where none were due. Nobody links it to the rewrite, because the rewrite happened months ago and was not even the last thing that changed.
Any inherited codebase where an old function encodes rules that live nowhere else. Most
common in logistics SLA tables, banking fee and penalty rules, insurance eligibility,
payroll, and pricing. The giveaway shape is a function whose ugliness grew one exception
at a time: somebody added a case in June, another in October, a third for long-haul
routes, and never wrote any of it down. P5's inherited repo plants this exactly:
src/sla.py holds a monsoon exception for tier-3 destinations, a festival exception for
standard service in October and November, and a long-haul rule above 1,400 km. Linked
modules: P5 (Team project on inherited broken codebase), 4.5 (Testing ML code),
1.6 (Feature engineering and encoding), 0.2 (Git and GitHub as an engineer).
Ugly and wrong are two different findings, and teams treat them as one. Reading is how you form a suspicion. It is not how you confirm one. The moment a team says "this is unreadable, so it is probably wrong", they have swapped evidence for a feeling.
The second trap is the handover note. Departing authors write these in a hurry, on their
last day, from memory, about code they last touched months earlier. They are honest and
they are unreliable. In the P5 repo the note says the tier-3 logic in sla.py is
"definitely wrong" and should be rewritten first. It is not wrong. It matches the
promised delivery window on all 18,000 rows in the data file, including every exception.
A team that treats the note as a fact loses two days on the wrong file and ships a real
regression.
Here is how to tell the two apart before you touch anything. Take the old function and run it over every row of real data you have. Compare its output against something in the data that must agree with it — a stored value, a downstream field, a report the business already trusts. If they match everywhere, the function is correct and its ugliness is a cost, not a bug. If they disagree, you now have the exact rows where they disagree, and those rows tell you which rule is missing. Either way you have evidence, and either way you can now write the rules down.
The last piece of the diagnosis is why the rewrite passed review at all. Nobody could state what the old code did, so nobody could say what the new code failed to do. A review of a rewrite is worth very little when the reviewer's only reference is the diff.
Immediate: if the rewrite is already live and records are wrong, do not patch forward.
Find the old version in git history — it is still there — and compare the two functions
output by output over the full data set. git log --oneline -- path/to/file then
git show <sha>:path/to/file > /tmp/old.py. The list of rows where they disagree is your
incident report, and it goes to whoever owns the affected records before you write a fix.
Structural, and in this order. First write a characterisation test: a test that runs the ORIGINAL function over a large slice of real data and records what it returned. It is not checking that the answers are right. It is pinning what they are, so any future change that moves them shows up as a failure you must explain. Commit that test on its own, before the fix branch exists.
Second, mine the test for documentation. Every branch the characterisation test lights up is a business rule somebody once needed. Write each one into a plain-language table in the repo, with the input range and the output it produces. That table is the deliverable the original author never wrote.
Third, decide with evidence rather than taste. If the function is correct, the honest register entry is "ugly, correct, LEAVE IT" and the effort goes somewhere that is actually broken. If you still want it readable later, refactor in small steps behind the characterisation test, changing shape and never behaviour, with the test green after every commit. Never rewrite and re-specify in the same change.
Make "prove it is broken" a written rule of your team, not a mood. A defect register that allows a row with no evidence will fill up with opinions, and opinions rank badly against risk. Two columns fix this: what you observed, and how a reviewer reproduces it.
Treat every inherited handover note as a list of leads, never a list of facts. Copy each claim into your register as an unverified row and close it with evidence, including the claims that turn out to be true. In P5 one claim in the note is wrong and one is right, and only testing tells you which is which.
Then protect the knowledge. Any function that encodes rules from outside your team gets a characterisation test on the day you inherit it, even if you never plan to touch it. Add a comment at the top naming where the rules came from and who to ask. Rules that live only inside a branch of an if-statement are one confident afternoon away from being deleted.
Q: "You inherit a function that is unreadable. What do you do?" Weak answers start with "refactor it" or "rewrite it with better names". Strong answer: say that unreadable and incorrect are separate findings, and that you cannot rank the work until you know which one you have. Then give the method — run the old function over real data, compare against something the business already trusts, and record what you find. Name the outcome both ways: if it matches everywhere, it is a readability cost you schedule, and you write a characterisation test plus a rules table before anything else; if it disagrees, the disagreeing rows are the specification for the fix. Strongest answers add the failure mode: a rewrite of code nobody understands cannot be reviewed, because the reviewer has no reference to check it against, and the rules you delete will not fail until the season that needed them.