I don’t know about most developers, but there is a very specific kind of sinking feeling you get when you join a project, clone a repo, and realize you’ve just inherited a total disaster. I’m talking about the kind of codebase where you don’t even know left from right: unhelpful generic variable names, no documentation, and a slew of bugs. You probably tensed up remembering a scenario like this. If you haven’t, then you are lucky, because sure enough, at some point in your career, it will test your sanity. I hope what I write about here will help you avoid that. I mean the part about losing your sanity—because let’s face it, the crazy, Frankenstein codebase is inevitable; the breakdown doesn’t have to be.
Look, Don’t Touch.
This first phase is probably the hardest because, if you’re anything like me, your instinct will be to start deleting and refactoring things immediately. Resist that urge. When you’re in a codebase this messy, you literally don’t know what you don’t know. That weird, 500-line nested if statement might actually be holding the entire production environment together.
Before you change a single line, you need to map the data flow. Where does information enter the system? Where does it leave? Don’t worry about how it’s doing it yet—just focus on the what. Dig into the git logs to see who wrote what and why. Usually, if you look closely enough, you’ll start to see the patterns (or the lack thereof), but the story of how the codebase got there will become clearer.
Employ Constructive Destruction.
Basically, you are going to start breaking it, but in a way that will help you figure out what to fix and how to fix it. You cannot improve a codebase if you are terrified of breaking it, but you also don’t want to take down production. So what we will do is set tests around validating what the functions do and do not do.
You want to set them up so that they pass with the current implementation. That way, as you start to fix (break) things, you can use the tests to ensure that you aren’t breaking any of the areas of the app that are working correctly. It might be tedious and not the most fun, but if you implement them, you can immediately start changing things with the confidence that you have a system that will warn you if you make one change too many.
Remember the Boy Scout Rule.
The Boy Scout Rule is to leave the campsite cleaner than when you arrived. The same goes for developers: Leave things cleaner than you found them. While you are working and you get more and more understanding, you will start finding more and more areas of the application that could probably use a good cleaning up.
If you are working on a specific set of functions and you see some poorly named variables, change ’em. You see a bunch of repeated code, create a shared function that gets called instead. See a function that is really confusing and hard to understand? Add some comments that help with understanding. That way, the next time you need to come back and do something, or when a new engineer needs to fix something, it will be readable and understandable, speeding up later tasks. In my experience, these small cleanups eventually hit an inflection point. Suddenly, the app starts performing better, and the ‘dark corners’ of the code aren’t so scary anymore.
Avoid Blame.
This actually might be the hardest but most important thing to do: avoid blaming or criticizing the people who wrote this code before you. I am not saying not to recognize the issues, but rather not to just blame the engineers who came before. There are a whole slew of reasons that a codebase could end up in a Frankenstein state. The timeframe to ship could have been ridiculously short, the requirements could have been shifting daily, even multiple times a day, depending on how long ago the code was written, and that could have been the best strategy at the time. Practices and strategies change fairly quickly in our field.
Improving a poorly architected codebase is a marathon, not a sprint. It can be uncomfortable, frustrating, and a little overwhelming, but it is also one of the best ways to truly master your craft. If you take your time and are methodical, you can turn even the most tangled mess into a foundation you’re proud of. And if all else fails, remember: talking through the logic out loud to an inanimate object usually does the trick. Now go grab that duck and start cleaning up that repo.