The Shape of the System

The Rewrite Trap

The ugly working system you want to delete is a scar map of every wound it has survived, and you are about to throw the map away.

planning operating retiring

You take over someone else's codebase and within the hour you've found it. Some function with a name that tells you nothing. It's got three layers of special cases piled on top, and there's a comment that just says do not remove this, it breaks billing. Nothing's named the way you'd name it. None of it is clean. And then a small voice in the back of your head, a righteous one, pipes up and says we should just rewrite this. Bin it, start over, do it properly this time. The voice sounds like competence. It's the most expensive instinct there is in this job.

The ugliness you want gone isn't mess. It's memory. Every odd branch in that function is a bug that happened once to a real person on a real day, and the fix is parked there in the code because somebody worked it out the hard way. The code is ugly because the world is ugly. The code has been places you haven't been to yet.

Joel Spolsky said the thing nobody warns you about, and he said it twenty-six years ago now: reading code is harder than writing it. That's why the old code reads like rubbish to you. And it's why the rewrite, the one in your head, is going to be clean - obviously it is, you haven't written it yet. No scars on it because it hasn't met anything that bites. Give it time and it'll grow the same lumps, the same do-not-touch comments, because the lumps were never somebody's bad taste. They were edge cases, written down. You delete the code and the lessons go with it. The bugs don't go. They sit there and wait to be found all over again, in the same order, by you this time, only now there aren't any comments left to tell you what they were.

And the whole time you're rebuilding, the old thing is sitting still and the world isn't. Nobody puts this in the estimate. Back in 2010 there was a site called Digg - at its peak it was big enough that linking to something would knock the server flat - and they decided to rebuild the whole lot from scratch, new everything, new database underneath it. The rebuilt version went out at the end of August. It pulled out features people loved and it shipped full of glitches, and the users didn't bother filing bug reports. They just left. They got up a leaving day and the whole lot of them walked over to Reddit inside a single week, and Reddit changed its logo for a bit to wave them in. Couple of years on and Digg's audience was down something like ninety per cent off its peak, and the company sold for about what a small flat costs. The rewrite didn't slow Digg down. It handed the audience straight to a competitor, gift-wrapped, and it took no longer than it took to ship.

The rebuild is never the clean copy you said it'd be, and there's a reason for that. The minute a team gets out from under the old constraints, in comes everything. Every feature they ever wanted. Every architecture off some blog post that made it sound wonderful. Every grudge they've been carrying about the old design, all of it pouring in at once, because now they finally can. Fred Brooks put his finger on this in 1975. The second system somebody designs is the most dangerous one they'll ever build, fat with all the clever bits they had the sense to leave out of the first one. The rewrite is the second system. Being free of constraints doesn't get you to elegance. What you get is a cathedral nobody can get into.

None of which means never. Sometimes the platform genuinely is dead, or the language isn't supported any more, or the people who understood the thing have gone, and you're stuck. But the honest version of the rule is a lot narrower than the slogan makes out. What fails over and over is the big bang - freeze the lot, go off and rebuild in the dark for a year, and hope to God the new thing's ready before the old one keels over. It was never rewrite versus refactor. It's big bang versus one careful step after another. Even Brooks, who'd told everyone to plan to throw the first version away, went back on it twenty years later and said he'd got it wrong, that you build the thing a piece at a time or you don't really build it.

There's a tree that shows you how this is meant to go. A bird drops a seed up in the high fork of some older tree and it sprouts there in the canopy, and it sends roots down the outside of the trunk, slow, year after year, until they hit the ground and thicken up into a lattice all round the host. The old tree keeps living through all of it. Then one day the lattice can hold itself up, the host inside has died and rotted off, and what's standing there is the new tree, hollow where the old one used to be, holding its own weight. They call it a strangler fig. It's the only way anyone has ever reliably swapped out a living system. You grow the new code round the old, one route at a time, one function at a time. Every step ships. Every step you can back out of. There's never a point where you've got two systems and a prayer - you've got one working system that's quietly turning into a different one, right up to the day the old code is holding nothing up and you delete it without any fuss, because it's already dead by then.

The mess was never the enemy. It was the map. You pay it off slowly, and you pay interest on it. You don't pour petrol over it and walk off.

In the manifesto, this is tenets (XX) and (XXI).

Sources

One of a series of field notes on building software for the way minds actually work: tired, distractible, ordinary, and now partly machine. They all lead back to the manifesto behind them, The Shape of the System.