← Back

Clean Slate

A working method for refactoring large codebases

I’ve learned something about myself recently. I work best on a clean slate.

I’ve always loved to format my computer and start fresh with a reinstall. I never ever put back any backups. I feel there is no need. Before I format I do of course check if I have any documents or pictures on the machine locally that are not synced to the cloud. But after the format I download some of the applications I’d like to continue using and I’ll tweak my settings a bit so they’re back to how I like them, but that’s it. I feel like it gets rid of all the junk and unnecessary stuff that piles up after using it for so long. You can spend a lot of time searching for old stuff and deciding if it can be removed. Or you can reformat the computer and only put back what you need.
This also applies to reformatting my phone. I only download back whatever apps I’m truly using. It gets rid of those apps I download once and never use after a while.
It turns out this same principle, the same metaphor, can be applied to developing.


At Maxxton we’ve reached a point in our software where we noticed the code wasn’t that maintainable any more. Two or three years ago some foundational choices were made without knowing where we would stand two or three years later. The software has grown bigger than we anticipated and as a result the code is starting to form cracks.
In my team, several developers have been working on the same parts of the software for quite some time, adding or removing stuff as time went on. New clients came in with a different way of working that we wanted to support or we changed stuff based on new found information. The code slowly grew into a Frankenstein’s monster and could be used as a school example of “spaghetti code”. Bugs were common and it was easy to break stuff while working on a different thing.
So a bunch of weeks ago we decided to do a big refactor of one of the most error prone areas of our software. Use proper State Management and building the code while knowing what we know now.
Me and my teammates each got our own part to refactor and went ahead with this pretty massive job.
It turns out though that my teammates have a very different approach than me though.

Slow down and focus

I love doing the refactor. I get to revisit code that has been written a few years ago, possibly even my me, and make it better. Do you ever have that, when in hindsight you think of better ways to develop a particular feature? Well, I do. And normally I don’t really get to revisit it, but now I do! And there’s at least a year of extra knowledge in my head on how to do it better. It is very satisfying.
But it is difficult. Before tackling a certain page or component, I spend quite some time analysing it. How does it work? Is it supposed to work like that? What happens at every step? What stuff is still needed and what can be thrown out? Think of it as Marie Kondo for your code.
Do you know the proverb “not being able to see the wood for the trees”? The Dutch equivalent for that proverb would translate to “not being able to see the forest through the trees”, which works slightly better in my opinion. This is often the same thing when looking at a large codebase. The amount of code can be so overwhelming that it’s hard to figure out what it all is doing. It’s more difficult to understand what all of it is doing if you’re trying to take it in as a whole. For me, parts of the code I don’t really have to look at at that moment are creating noise which hinders me from truly understanding the parts of the code I am trying to focus on. Isolating parts of the code helps me to focus on it. Therefore I always like to create an empty component or page next to the original and start fresh. I find it simpler to write everything again from scratch having the old code as a reference from which I can copy and paste of necessary. I can take pieces of the code and isolate them in this new component. I can start with improvements to the overall layout if necessary—which is easier if there isn’t a ton of code inside them— and add pieces of the component or page back one at a time. And by checking every parameter while I type them in allows me to follow it and see if it’s still necessary. Starting fresh on a clean slate forces me to slow down and helps me focus on one thing at a time. My head is much calmer than when it’s filled with the noise of a whole lot of other person’s code. Eventually the code in the new component will grow and grow but the code already there won’t be as noisy as before as I already understand what it does and what its purpose is.

It might seem tedious

It turns out though that in my team I’m the only one that prefers to work like that. My coworkers seem to prefer converting components as they are. Rewriting bits and pieces to work with the State Management that we are implementing. That can work just fine, but in my experience you end up with a lot of old code that if you were to look closer, could actually be removed. In my experience it’s also very hard to wrap your mind around all of the code to understand what it is all doing and what parts are needed and what parts could be further optimised or even dropped. So you end up with refactored code that you don’t really know as well as you should.
In my experience it takes a fair bit of domain knowledge in order to successfully refactor code in this manner; Knowing what the code does and what it is supposed to do. But on large codebases or old codebases this domain knowledge is either lacking for new developers or everything is fuzzy for developers who are around longer at the company. In my case there could be parts I haven’t worked on, or parts I did work on but have been tweaked and changed by others over time, or parts I simply forgot how they were constructed or should work because it has been a while since I worked on it. It happens more than I would like to, that I wonder who wrote that subpar piece of code only to find out it was me a year and a half ago. But hey, we all grow, we all learn, and we all get smarter over time. It’s only in retrospect that we often know the full scope of the problem we are solving and how the solution we just build lacks or could have been build better. But it’s a luxury if you get to revisit and improve on it. Most teams work with deadlines and customer expectations. Those working in agencies even more than we do at Maxxton with our enterprise B2B software. You sometimes have to make due with something that you could perhaps do a better job on if you got to revisit it.
In that aspect, even refractors can be constrained by time. Developers are expected to refactor a portion off the application within a certain timeframe. In our case at Maxxton we’ve already extended that deadline by a month and we’re still not gonna make it.
My method might seem tedious and more likely to take up more time since I’m basically starting from scratch instead of modifying what is already there. But I beg to differ. The clean working area gives me the focus I need to fix the HTML groundworks. Things might have been added over time that I can now take into account when creating a better scaffolding. I get to revisit every feature and method one by one, figuring out how they work and how they’re supposed to work without any other features interfering. I would say that that increase in focus and decrease in noise actually increases my productivity and efficiency. I can often copy paste decent chunks of code and in other cases I can type referencing the old code.
This new intricate knowledge of the code also helps me on the long run. I own the code more and if I were ever have to revisit again due to a bug or a new feature I would be better able to solve the bug or implement the new feature. I’ve already been noticing that in the short timespan that we’ve been doing the reactor. I’ve been able to quickly and accurately answer questions about how certain parts of the code work to other coworkers.

Give it a try

I’m not yet sure if this working method works best for all or just for me. Why else would I be the only in my team working like this, no? It could very well be a lack of domain knowledge on how it all is supposed to work that refrains my coworkers from also working from a clean slate. They might think all bits and pieces are vital. I don’t know. I might bring it up during the next retrospective. If you yourself have been in similar situations, or still are, and you have any input on this I’ll be extremely curious to hear. Or be sure to try it out next time and let me know then.