Legacy Code: 7 tips for approaching code you didn’t write

I was recently presented the opportunity to jump on a project that has been running for 6 years and is easily a thousand files strong. Much of my past engineering experience has been centered on smaller projects that I either created or had direct access to the person who did. Thus, I was a fish out of water inheriting a project of this magnitude. I am writing this post to pass down some words of advice so that your transition will be both productive and as painless as possible.

Embrace the Past

What’s done is done. Getting frustrated over a specific implementation won’t do you any good. There are tons of factors out of anyone’s control that could‘ve contributed to the current state of the project you have inherited. For example, maybe the developers were dealt a tight deadline, or they didn’t have all the information they needed in time to make the architecture what it needed to be. We have all been there. It’s best to adopt a constructive mindset and use inheriting legacy code as an opportunity to show what a great developer you are! If you can see issues in code other people have written, pat yourself on the back and remember: Don’t Kick The Can.

Don’t Kick The Can

When there are hundreds or thousands of files in a project, chances are you may never need to explore all of them. That said, if you are working in a file where you realize there are major “issues,” don’t kick the can. Make other team members aware of your concerns with the file in question. Again, at least let somebody know. If possible, make the improvements you can while you are working in that file. A solid practice would be to leave a well documented comment in areas of concern and creating corresponding tasks in the backlog to set aside designated time for improvement. You will make someone else’s life easier when working in that file down the road.

Refactor, Test, Refactor

Making things better generally isn’t easy, especially when you are working in a massive project where one file change comes with an avalanche of ramifications. That said, refactoring and writing tests is a great and proactive way of familiarizing yourself with the project that you inherited. The thought behind this is that to refactor and test a feature or specific implementation you will have to truly understand the behavior of the code and the issue the code is addressing. This process usually gets the developer diving into files he/she had no clue existed and will quickly improve your knowledge of "where things are happening."

New Feature? Pick Me! Pick Me!

Let’s be honest: inheriting legacy code is never easy. Even if you go at it with the best mindset, piecing together an understanding of someone else’s thought process can be both very challenging and mentally draining. That’s why it could work to your benefit to volunteer for building out new functionality. Nothing is better than the opportunity to start fresh. You will definitely feel rejuvenated contributing some well-written and well-documented code to a legacy project!

It’s Ok to Bug Me

Developers usually loathe bug fixes. They carry a constant undertone of “busy work.” However, taking on bug fixes can be another great way to gain exposure to a new code base. I was afforded the luxury to take on what were deemed “small” and “manageable” bugs at first. Small victories from squashing bugs furthered my understanding of many of the various features’ architectures and provided me a channel to contribute to the rest of the team very quickly.

Documentation—Leave a Paper Trail!

If you’ve inherited a legacy project, chances are you’ve experienced frustration over not understanding what the previous developer was trying to do. I pray you never see a 300-line method with high cyclomatic complexity and without any comments. Save yourself and others time down the road by writing well-documented comments for classes and methods. Let people know what method “X” should be used for so they don’t have to waste time finding breadcrumbs and guessing at functionality.

Communication is Key

I have noticed that a huge contributor to success on a large legacy project is communication. Never be afraid to lean on your teammates. If you are working in a file or on a feature that a teammate built, do not hesitate to poll them with questions and try to understand their logic. It will definitely make things easier.