How do you work safely with legacy code?
Legacy code is code you depend on but are afraid to change, usually because it has no tests and nobody who wrote it is still around. To work with it safely, learn what it does, pin that down with tests, then change it in small steps.
In audits of codebases, mostly for mergers and acquisitions, 92% had open source more than four years out of date, and 93% had components with no new development in two years.
From my work
Most of my projects started with someone else’s code: Itmatched and Mom Software, for example. At Itmatched the product was an MVP that had grown for years and was not live yet. We fixed the legacy code and migrated what needed migrating first. When the requests for gift cards, promotions and analytics pages came, I pushed back: those could ship after launch. We went to production on time.
Read before you change anything
- Run the app and use it as a customer would. Write down what each screen does.
- List the dependencies and their versions, and check which ones still get security fixes.
- Find where the data lives and who writes to it.
- Fix a few small bugs on purpose. It is the fastest way to learn how the code really behaves, which is rarely how the README says it does.
Pin down what the legacy code does with tests
Before a change, write tests that record what the code does today, even the odd parts, because something out there may depend on them. Michael Feathers calls these characterization tests in Working Effectively with Legacy Code, a book that defines legacy code as code without tests. Whether the code is right can wait. For now you only want to notice the moment it changes.
Start with the flows that make money: sign-up, checkout, the core action. An end-to-end test on each covers more than a hundred unit tests on code you do not understand yet.
Change it in small steps
- One change per merge request, small enough to review in a few minutes. Big merge requests get approved. Small ones get read.
- Rename and move code in one step, change behaviour in another.
- Upgrade one major version of the framework at a time.
- Ship each step to production before starting the next, so you know which one broke something.
When to rebuild instead
Developers like to say that old code has to go. Usually it does not, but sometimes the code really is too messy to fix in place. Then build the new version next to the old one and move it over a piece at a time, with a routing layer in front deciding which version serves each screen or endpoint. Martin Fowler calls this the strangler fig pattern. At Mom Software the Angular 10 app followed no pattern, so we started again on a Fuse template and moved the old code across module by module.
That is different from a big-bang rewrite, where the team stops and rebuilds everything before anything ships. Moving piece by piece means you always have something working.
When to leave legacy code alone
Old code that works, gets security fixes and that nobody needs to change can stay as it is. Old is not a problem. Old and in the way is.
The signs it is time to act
- The framework or runtime no longer gets security updates.
- A library you depend on is abandoned.
- Every feature takes longer than the last one.
- You cannot hire developers who want to work on it.