Don’t Rewrite that Code
This is a plea to the perfectionist in all developers — don’t rewrite that code!
Most engineers with experience on a multi-year long project have experienced something like this:
“Okay, just quickly digging through this dusty bit of code. I just need to add a bit to that old legacy component. Here it is, I’ve found the bit of code I need! Easy! Oh wait… is it here, or this other identical file? Dear lord, how many places has this been pasted around? And where in the heck does this state live? Wait, you’re telling me I have to modify a completely unrelated part of the project to get this to run? You know what, I’m done reading this. Burn it all to the ground, this needs to be rewritten.”
I get it. I really do. But wait! Don’t let your emotions get the best of you. Before you press on smashing the delete key with a satisfying smack, I have some points I would like to make in favor of live and let live — give that terrible code as little of your energy as it deserves and move on.
“This code is bad.” Why? “Well, I didn’t write it!”
I have heard it said that programming is one part math, one part science, and one part art. Do not let the “art” bit cloud your judgement when evaluating the merit of perfectly valid “math” and “science.” Every programmer’s ego insists that they, and only they, have the true best way of organizing code. All of us are dreamers and creators at heart and understandably love to create new things from scratch. We also hate to read and understand code written by others, because frankly it is exceedingly difficult to do.
It is important to be honest with yourself when looking at others’ choices in problem solving. Is it truly a bad approach or just a difference in style? No two people are alike, and the reality of writing code for money is that you will have to work with others with differing perspectives. Even if it is a “bad” approach, does it really matter at this point?
Who wrote this code, and when?
One of the best books recommended to me about being a software engineer is The Mythical Man Month. For those who have never read it, it’s a post-mortem describing the engineering process and fallout from IBM’s development of OS/360, which was was one of the world’s most complex software systems created in its day. The engineering effort surrounding it was massive and many painful lessons were learned and are still talked about to this day.
One message the book preaches is that in any successful engineering organization, creative autonomy must be delegated successively downwards. That means that a (software) architect is responsible for architecture, a senior engineer is responsible for a feature end-to-end, and a junior engineer is responsible for implementing a small specification in code. The architect, while undoubtedly more experienced and an accomplished coder, should not in any way interfere with the process of the junior engineer. It’s simply not effective or scalable to have high level project members spending their days doing base engineering work.
Why am I mentioning this? Well, you should ask yourself if you’ve been the architect breathing down the neck of a junior engineer . If this was written by somebody new to the profession of software, it was a learning exercise. It probably wasn’t perfect. However, if this code is still their responsibility, don’t tear it down! Even if it isn’t as “good” as you would do it. Using objective language, explain what you think should be different and why and come to a solution with them. Turn a critical message into a constructive one. This is how junior engineers grow and become senior, after all. An added bonus to this technique is you don’t have to be the one to rewrite it!
Different style than you like?
Be a champion of your team’s style guide. Create a linter configuration and run it on your codebase, then pat yourself on the back for being awesome. No rewrite necessary!
Is the code understandable?
If you can understand how the code works and are able to modify it with relatively few edits, you are likely gaining nothing from a rewrite. Remember, reading other peoples’ code is way harder than writing your own! If you managed to do it without too much head scratching, then that code might actually be pretty darn good.
The parable of Netscape
If you haven’t heard The Story of Netscape 5.0, boy are you in for a treat. While I could copy at length from Joel, just read the linked article. For those readers uninitiated, Joel on Software is arguably the greatest programming blog ever written.
There’s a reason that code was hairy in the first place
No plan survives first contact with the enemy. Or as we all love to say, everybody has a plan until they get punched in the mouth. The same goes for software design.
Sometimes, code is complicated because surprise, it needs to serve a complicated functionality! Perhaps requirements were unclear or incomplete at the first time of writing. And let’s not forget the potentially dozens of bug fixes that may be sitting in strange, crusty places. Through weeks, months, or even years of usage, this code has had hairy bits and pieces added to support real world use cases. Is it always pretty? No. Does that mean you should spend time rewriting it? Well, I guess that’s the whole point of this article. My personal reaction is a strong NO, if “pretty” is the only reason!
Oh, well it shouldn’t take that long anyways
Make sure you’re really confident about that one. As we all know, software engineers are famously good at estimating how long things take.
Premature optimization is the root of all evil
Part of understanding the benefit of rewriting this code is understanding what you stand to gain from cleaning it up.
Have you measured, verifiably, the slowdown, pain, or otherwise cost of this code being “bad”? You don’t need to run a double-blind study but get something more than the general opinion of yourself and your teammates. Point to bugs that came out of the code — git file history. Instrument and measure the slowdown from this code. Document the extra effort it took you and others to work with it. If you find it difficult to measure the problems caused by the code, perhaps it wasn’t really causing any in the first place?
Note — If you have no way to profile your performance-intensive code, build it! We are computer scientists after all, and what good is a scientist without measurement? I’ll leave that thought for a future article.
How active is this code?
One of the largest benefits to rewriting code is to make it easier to edit in the future. Make sure that this code is actually going to be changed more than once a year from here on out. If it is an active piece of code, then the value of rewriting goes up significantly.
That is, if the rewrite works correctly (execution is key, people!) The cost to your team of disrupting a core piece of their infrastructure is high.
We’re in this to make money, not write code
I get it, we love the craft of development. It’s a fulfilling career. But at the end of the day, we’re here to make money. Businesses don’t make money by throwing away working code. Especially not for the sake of aesthetics.
By association, you don’t get a paycheck to write code without purpose. A danger with rewrites is how dang good it feels compared to how much it’s actually accomplishing. Before you embark down that rabbit hole, I’d urge you to consider spending your time on things from the following list:
- New feature
- Improving test coverage
- Writing documentation
- Build and release automation
- Picking up a bug off the backlog
At your next performance review, what do you think will get you a higher bonus — rewriting this code, or something I just mentioned? Don’t screw your own career by working on invisible things which your company can’t justify rewarding.
Okay, so should I never rewrite code, ever?
Well, here’s the fun part where I contradict myself. Obviously, technical debt is a very real thing. It simply can’t go unaddressed forever. We do need to update code over time and invest in refactors and re-designs to maintain the health of a software project. I will give the following high-level pieces of advice for any rewriting of software:
Do a little bit at a time, over time
The best software engineers I know do this. Clean up as you go. Split that massive procedural state machine block into interfaces. Break apart pieces that don’t need to be together. Move that copy + pasted junk into one function. Please avoid massive swathes of rewriting. Never throw away the true functionality going on underneath it all.
Understand the requirements
I have no doubt you’ve spent too many braincells trying to understand what the current code does. But please, spend at least as much effort planning your new design. Again, it’s easier to write than read code. So, when you put together your grand plan to make everything awesome and wonderful with an innovative design, consider the consequences.
That includes the poor sap showing up to this project in 5 years’ time who will never meet you and work purely with the code left behind. Sometimes, a basic, less elegant design (procedural if statements in a 10,000-line file) is easier to maintain than an over-engineered design pattern spread over a wide area.
Justify the business impact
Always justify this with business impact. That can be an upcoming feature which will be made possible to implement. It could be bugs generated from this block. It could be performance, or the quantified engineering cost of maintaining it. Anything works if you can point and say why. Then, they tend to give you more money at the end of it all!
I do want clean code, though
As a wrap-up to this article, I would like to clear up a few things:
- I am a proponent of clean code
- I believe reasonable coding standards should be enforced on projects
- I always prefer to write modular, hierarchical, object-oriented software
If I see code which isn’t up to these standards, I too feel the siren calling of a rewrite. But first, I ask myself what the benefit to the company is, as well as myself. After that, I usually go about my day happily doing other things. When the feeling gets too strong, I might even write an article like this to convince myself.
Happy rewriting (or not) and have a good day!
Disclaimer: This article contains an affiliate link
