What is legacy code and how to avoid it?

Have you heard “legacy code” as the reason when something went wrong in a software project? Understanding legacy code is crucial because it occurs in every project sooner or later. We use the term loosely to describe old code that we don’t like but what is legacy code really and even more importantly how can we avoid it?

First understand what is legacy code and then learn to avoid it by investing in stable teams, prioritising maintenance and making writing tests a habit.

Legacy code is someone else’s mess

If you want to be really strict with the definition of what is legacy code you can say that it’s all code that you didn’t write. That makes legacy code a highly subjective thing. Because my code is your legacy code and the other way around.

Time makes legacy code

So let’s be more specific about what we usually mean when we talk about legacy code. An important factor for legacy code is time. Legacy code is not just someone else’s code, it’s also old. It’s the legacy (of code) that someone else left for you. That’s a pretty workable definition and also gets to the point why it’s so common in software projects

This shows that time is an important factor for making legacy code. If your code does not change but everything else moves on the code turns into legacy code.

Unstable teams have more legacy code

The more common it is for software to change ownership the more legacy code your organisation will have. If your team is stable and people don’t leave for other jobs then it’s less likely that your engineers label their codebase as legacy code.

What is perfectly understood and maintainable code is utter legacy code for a new team member. So what is legacy code and what is not depends on who you ask.

How organisations create legacy code

Besides time and unstable teams it’s often the organisation itself that aids the creation of legacy code. Imagine that you wrote an application and it just keeps on running smoothly. No necessary updates, no new features. Would you call it legacy code? Probably not, because it doesn’t cause any troubles.

What is legacy code? Legacy code is like a smoker’s lung: Still functional but degraded.

So legacy code is not just any code, but code that matters. And it’s the organisation’s fault for letting a core piece of their business go rotten. Every organisation needs to invest in maintenance and care for what keeps the business alive. You can get away with not caring for important parts of your codebase just like you can get away with smoking for a while but it will catch up to you eventually. And it might be too late by then.

Another way your organisation can cause technical debt is through misaligned incentives. Be careful if you reward teams or individuals for shipping features and hitting deadlines. The unseen fallout is often legacy code because nobody gets rewarded for doing it sustainably or maintaining existing code.

Technical reasons for legacy code

Besides time, unstable teams and organisations not prioritising maintenance there are also a myriad of technical reasons that can turn your code into legacy code.

If your codebase turns into legacy code because more and more dependencies, APIs and frameworks you’re using are becoming obsolete it might not always be the businesses fault. Sometimes legacy code is created inadvertently by the engineers because they might not be aware how fast dependencies get outdated. In fast-changing ecosystems like JavaScript this is a real problem and not easy to always stay up to date.

Legacy code is untested code

Another great example for what makes legacy code is untested code. Tests document the intended behaviour of code which is a tremendous help for future developers to understand it. Your engineers might not be aware of the benefits of testing, don’t have enough experience in it to make it an engrained practice or they might simply be pushed too hard to make the time to write tests. In either case the result is legacy code.

How to avoid legacy code

So far we have answered the question of what is legacy code? and what the various causes for it are. But more importantly is how we can avoid creating legacy code in the future.

Here are some solutions for the problems above from an organisation’s perspective:

  • Retain talent and build stable teams
  • Allocate resources for maintenance of your existing codebase
  • Incentivise and spotlight maintenance and refactoring achievements

From a technical perspective here is what you can do:

  • Monitor dependencies and define upgrade plans
  • Create coding standards and introduce best practices like automated tests as a must-have

As an individual what you can do is:

  • Make refactoring a habit and leave things in better than you found them
  • Skill up and learn how to write automated tests

Legacy code is the entropy of software engineering

The more time passes and the less you actively invest in maintenance the more legacy code you will face. In that sense legacy code is the entropy of software engineering. As a business you need to understand the inevitability and harm of legacy code and fight it continuously. As an engineer you can build a habit of maintaining and refactoring and learning how to write better tests. However, you can’t beat legacy code on your own so both your organisation and you need to work together to really overcome legacy code.