The Rewrite
A team is sure the legacy order system is garbage and the rewrite will be clean. Echo has the new repo open. Root makes her read the ugly old code aloud, branch by branch — because each weird thing is a scar, and a scar is a lesson someone already paid for in an outage.
Burn it down only when you can name, out loud, every fire the old thing was putting out.
Echo had a new repository open, one commit deep, and the commit was called initial.
She'd pushed for it for a month and they'd finally said yes: rewrite the legacy order system — the one everyone hated, the seven-hundred-line function, the comments that lied. "Eight months. We delete the whole rotten thing and never apologize for it again."
Root pulled a chair to her desk and did not look at the new repo. He looked at the old one. "Before you delete it. Read me the ugly parts. Out loud. Every one."
"That's the point, I don't want to—"
"Read me the seven-hundred-line function. Not what it should be. What it is. Every branch that makes no sense."
So she did, grudging, then less so. The function that checked the date three different ways — because three upstream systems sent three formats, and one was a bank that would never change. The retry that waited a weird forty-one seconds — because a vendor's gateway rate-limited at forty. The dead-looking branch for orders with no customer — because once a year accounting pushed a correction that had no customer, and if it threw, the month didn't close.
Echo got quieter as the list got longer.
"Keep going," Root said. "You're about halfway through the reasons your clean rewrite is going to rediscover at two a.m. in November."
"These aren't bugs," she said slowly. "They're scars. Every ugly thing is a scar. Something cut the system here once, and it healed crooked, and the crooked is the heal."
"And a rewrite that doesn't know the scars is just a body that hasn't been cut yet. It'll take every one of those wounds again, live, in front of customers, and call them surprises." He stood, finally glancing at the one-commit repo. "I'm not telling you never. Sometimes the old thing has to molt. I'm telling you the yellow cow."
"The what?"
"Old line. Wrap yourself in the hide of a yellow cow — bind your own hands at the start. Change only when there's nothing else to be done, and not one day before you can name, out loud, every fire the ugly old thing was quietly putting out. You've named maybe nine. Find the rest. Then we'll talk about initial."
Chesterton's Fence as an engineering disease: the legacy system is 'obviously garbage,' so a team rewrites it clean — and spends the next year rediscovering, in production, every weird branch the old code held, because each one encoded a real-world constraint nobody wrote down (a bank's date format, a vendor's rate limit, the once-a-year correction with no customer). The ugliness was scar tissue: a healed wound from a cut the new system hasn't taken yet. Joel Spolsky's "Things You Should Never Do" is the canonical warning against the from-scratch rewrite.
Inspired by Things You Should Never Do, Part I (Joel Spolsky).
Wrapped in the hide of a yellow cow. Changes should be undertaken only when there is nothing else to be done. Utmost restraint is necessary at first. Become firm in your mind, control yourself, and refrain from doing anything for the time being. Any premature offensive will bring evil results.
The figure. ䷰ Revolution (Gé), line 1 changing → ䷞ Influence (Xián). "Wrapped in the hide of a yellow cow" — changes should be undertaken only when there is nothing else to be done; utmost restraint is necessary at first, and any premature offensive brings evil results. Bind your own hands before the rewrite. The time to molt is not the day you first feel the itch.
The reading. Every ugly branch in old code is a scar — a lesson someone already paid for in an outage. Don't burn it down until you can name, out loud, every fire it was quietly putting out.
Department: Engineering (工)