Clean up as you go, but don’t clean everything

September 02, 2015

It’s good to take the opportunity to clean up your code as you go along, especially on big projects that will be maintained for a while. After all, the chances that you’ll go back and fix those little things later is pretty slim.

If you’re fixing a bug, and you see some improvement that could be made, perhaps to make the code more efficient or more readable, get on and do it. If you’re working on a front-end task and you spot an image that could be sprited, crack on. As long as you make the changes in separate commits, or ideally under a separate ticket, so that the code can be reviewed separately, why not just get it done?


As usual, there’s a but.

The difficult bit is knowing when you’re pulling at a thread that will unravel and leave you chasing your tail through a world of pain.

Sometimes it’s best to leave things alone. Let sleeping dogs lie. If it ain’t broke don’t fix it.

And sometimes even if it looks broken, don’t fix it. I’ve seen systems where the bad code in one place fits in with some bad code somewhere else, so fixing it might actually break some functionality.

If you’re not careful, you’ll get bogged down in a big pile of horribleness that nobody is paying you/your company to work on.

Sometimes you might agree that yes, you do need to refactor things, and you’ll put a ticket on your backlog and devote some time to doing something about your technical debt, preferably with a nice safety net of automated tests.

But if and when you do refactor, beware the temptation to imagine that your shiny new system will sweep aside all the old mess and solve all the problems.

Maybe you really are cleverer than the people who built that legacy system, and that your way is the right way to build it. But maybe you’re not. The people who built the old system probably weren’t stupid. They probably had to jump through some crazy hoops as the requirements evolved, and there might be some undocumented requirements lurking in the code. It’s valuable to remember the words of John Gall: “A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.”

The other important thing to bear in mind is that it’s a lot easier to maintain one complicated system than two, even if the second system is beautifully designed and follows all kinds of design patterns. Consistency is an underrated value.

This doesn’t just apply to code.

Digital evangelists want to spread their gospel, and rightly so. As Paul Boag says, a lot of organisations need to make fundamental changes to adapt to the digital world. Abby Covert has suggested that “if you see it as a mess, you can’t work here anymore, unless you’re going to fix it”. It’s easy to say, but what does it actually achieve? The organisation will still be in just as much of a mess. Perhaps you’ll no longer be personally blighted by that mess, and perhaps you’ll have moved on to somewhere shinier, but maybe you’ll have landed in a different mess somewhere else.

So maybe fixing it is the better option. Except that organisational mess tends to exist for a reason that is bigger than just nobody’s ever thought of cleaning it up. All organisations end up with their own messes. Even the shiny new startups have problems.

Yes it’s ugly, but so is the world. Sometimes you just have to accept the crapness of things, and get on with your job.

Much as some designers like to imagine otherwise, you’re not an artist, and you don’t have the right to throw a tantrum because the client doesn’t see things your way, or because your team chose to do something in a way that you don’t really agree with. Nobody believes musicians when they talk about “creative differences”, so why would they believe pixel-pushers and code monkeys?

In the meantime, there’s a lot to be said for getting things done that are already on your backlog