Managing legacy code and working on brownfield projects in the SaaS industry involves balancing innovation and stability. And that’s no easy feat.

Successful strategies often include things like phased implementations, leveraging existing assets, and continuous learning and adaptation within the team. 

These insights, specially designed for tech leads and founders, should provide a solid foundation for overcoming challenges and harnessing the opportunities of working with legacy codebases in our lovely SaaS landscape.

Embrace legacy in all its glory

Before discussing practical tips and advice on working in legacy codebases, you must consider the negative connotation of the word “legacy.”

Managers typically feel that the word discredits their past work and efforts, while developers will often hide behind the concept of legacy, which is always a culprit for delays, regression, and downtime. 

So, the first thing a technical lead working in a legacy codebase should always do is add context and “embrace” the word legacy. Why is there legacy in the project, and how did it bring you where you are today?

Another take on this: As soon as code is written and in production, it has become legacy. So, there’s no way around the concept anyway. 

Reading tip: Understanding and managing technical debt

Listen, watch & learn

When starting to work on a legacy project, your first job as a technical lead is listening, watching, and learning. You really need to understand what’s in place, architecture-wise, the state of the codebase, and all available resources before even touching anything. 

From our experience, the documentation in legacy projects is oftentimes either outdated or just lacking in general. Hence, during the understanding process, your first job is to fill in any missing parts (essentially killing two birds with one stone). Make the best of this knowledge transfer process. If the documentation is lacking, source it from the team and write it down.

Documentation is especially relevant to revealing less obvious dependencies, from used libraries to less visible infrastructure components to third-party system webhooks calling back.

It's good to have as much context as possible and learn about how the project evolved to its current state over time instead of immediately dictating how (one assumes) things should be fixed. 

Gain trust, improve velocity

Part of your job in the first weeks is to gain trust. You can do this by asking the right questions, learning the project, and understanding stakeholders' dynamics. Prioritize critical areas with stakeholders and roadmaps.

Our thesis for SaaS products is that delivering value to customers, constantly and consistently, keeps them engaged. We look for two things in the team: velocity and stability. Ask yourself these two questions: 

  • How fast are we shipping right now?
  • How stable will our product be once it's live? 

Technical leads can use the DORA 4 metrics to generate metrics that inform on these two things. Once established, you can set out a strategy for improving these metrics. That strategy will involve tasks that the team will own, but they will all be in service of improving DORA 4.

Incremental refactoring

There are several reasons why the state of a legacy project is what it is. When you start refactoring, do it incrementally and avoid changing massive code sections because this will likely have unintended side effects. This means gradually shipping small features and manageable changes. Shipping small changes often will increase trust in the engineering team as well. 

Also, apply the “Campground rule” of leaving the code cleaner than you found, which is pretty much the purpose or definition of refactoring.

Migration strategies: Big Bang vs Strangler Pattern

When dealing with brownfield projects, especially in cloud environments, there are two primary migration strategies: the Big Bang and the Strangler approach. The Big Bang involves moving all data and systems at once, which can be risky and disruptive. 

Conversely, the Strangler approach migrates systems in phases, moving functionality and responsibility elsewhere to minimize risk and ensure continuity in business operations. It's a good approach to gradually upgrading software and looking into microservices.

Reduced risk is the most important reason to consider a strangler application over a cut-over rewrite or Big Bang launch. A strangler fig can steadily add value, and the frequent releases allow you to monitor its progress more carefully. Many developers still don't consider this because they think it will cost more. However, we are not fully convinced. Since you can use shorter release cycles with a strangler fig, you can avoid many unnecessary features that cut-over rewrites often generate.

Adding features & tests

As you progress slowly and understand pieces of the codebase better, write tests for these specific sections of code. This will gradually speed up development time, as there is no need to recheck these sections manually. Think of it as reaching checkpoints along your journey when playing a computer game from which you can resume.

Do not underestimate the power of a good plan when adding new features, even if it takes a while to develop it. Avoid diving headfirst into development. Here are some quick tips or questions tech leads can ask to work through legacy projects. 

  • Use feature flags to introduce changes safely.
  • Reduce bus/truck factor in the engineering team where possible.
  • Ensure changes can be built and deployed with minimal intervention, or this will slow down the cadence
  • Start with shipping changes that are not visible to the end user to ensure the process works fine
  • Apply SOLID principles to classes

Are there automated tests to ensure the intended behavior is guarded?

Communication

Legacy codebases will present weird things and unforeseeable problems. Keep all channels open to your direct peers on the project and keep everyone informed of any issues, blockers, and challenges so everyone is on the same page. Don't suffer in silence. When it happens, ensure the people around you know these challenges.