What legacy code is, and how to analyse it.

01 / What legacy code is, and how to analyse it

A working definition.

A system is legacy when three things are true at once: it still does its job, something important depends on it, and the people who could explain why it behaves the way it does are gone or stretched. A six-month-old service written by a contractor who has left can be legacy. A thirty-year-old COBOL batch run with a maintained specification and a team that reads it is not.

That definition matters because it points at the fix. You cannot make code younger. You can make it understood.

02 / What legacy code is, and how to analyse it

How understanding is lost.

Decisions get made in code and nowhere else: a validation rule added after an incident, a limit that encodes a regulation from a particular year, a special case for one customer that became permanent. Documentation describes the system as designed, not as it runs. People leave. Interfaces to other systems grow without a register. Eventually the safest change is no change, and the system starts to constrain the business that owns it.

03 / What legacy code is, and how to analyse it

Legacy code and technical debt are not the same thing.

Technical debt is a choice made knowingly to ship sooner, with the intention of paying it back. Legacy is what remains when the knowledge needed to pay it back has gone. Debt can be prioritised and scheduled. Legacy has to be investigated first, because nobody can say with certainty what any given change will affect.

Treating a legacy system as a technical-debt backlog produces tickets nobody dares to pick up. Treating it as an investigation produces a map, and the map produces tickets that can be estimated.

04 / What legacy code is, and how to analyse it

What legacy code analysis involves.

Analysis combines several kinds of evidence, because no single one is complete. Static analysis reads the source and its build to recover structure, dependencies and dead paths. Dynamic analysis observes the system running, under representative inputs, to see which paths are actually taken and what they touch. Data analysis reads the stores, files and schedules to find the identifiers and relationships that give the code its meaning. Rule recovery traces each validation, calculation and approval step to where it is enforced and asks whether it is policy, workaround or fossil.

Each finding is tied to the evidence it came from, so a later reader can check it. Where the evidence is thin, the finding says so.

• Inventory: components, databases, scheduled jobs, interfaces, shared files, credentials, infrastructure
• Structure: what depends on what, and which boundaries are real rather than nominal
• Flows: how a task travels from screen or message through logic and data to the systems it affects
• Rules: the business logic, traced to its enforcement point and classified
• Record: architecture views, dependency register and rule register the organisation can keep

05 / What legacy code is, and how to analyse it

Refactor, rebuild or leave alone.

The investigation decides. Some components are sound and merely undocumented; they need a record and a boundary, not a rewrite. Some carry rules the business needs but sit on a platform it cannot keep; those are rebuilt behind a stable interface, one at a time, with a comparison against the original. Some are dead, and can be retired once the evidence shows nothing depends on them.

The worst outcome is a rewrite that begins before the rules are recovered. It reproduces the visible behaviour, misses the special cases that only appear at year end or under a particular customer, and discovers them in production.

06 / What legacy code is, and how to analyse it

Where to start.

Pick the system where the cost of not changing is already visible: a release that takes months, an integration nobody will touch, a vendor date that is approaching. Size the investigation around the question that system raises. The method, the deliverables and how an engagement is scoped are described on the software archaeology page.