Inheriting a Codebase Nobody Understands

The call usually starts the same way. There is a system running the business. The people who built it are gone. Something needs to change and nobody is confident about touching it.

The instinct in that moment is almost always to rebuild. It is also almost always wrong, and understanding why is most of the value of an audit.

What you are actually assessing

Not code quality. Quality is a poor proxy for risk and an even worse basis for spending decisions. What matters is narrower:

• What is load bearing. Which parts, if they stopped, would stop the business today.
• What is in the path of change. Which parts have to be touched for the things you actually want to do next.
• Where the risk concentrates. Which parts touch money, personal data or anything with a legal obligation attached.
• What is simply old. Which parts are unfashionable, stable, and can be left entirely alone.

That last category is bigger than people want it to be. A module written in a style nobody uses any more, which has not changed in four years and does its job, is not a problem. It is a solved problem that looks unfamiliar.

Why rewrites fail

A rewrite has to reach feature parity with the existing system before it can replace it. That sounds achievable until you notice that nobody has a complete description of what the existing system does.

The documented behaviour is a fraction of the real behaviour. The rest is accumulated: edge cases handled years ago for a customer who complained, a rounding decision someone made in a hurry, a workflow that only works because of a bug people have adapted to. All of it is now load bearing, and none of it is written down.

Meanwhile the old system keeps running and keeps needing changes, so you are maintaining two systems and shipping value in neither. This is the standard shape of the failure and it is very hard to recover from once it is underway.

The approach that survives contact

Put a stable interface in front of the old system, then replace behind it, one capability at a time, in the order the business actually needs.

This is slower to feel satisfying. There is no moment where the old thing dies and everyone celebrates. What there is instead is a sequence of changes that each deliver something, each of which can be stopped, and none of which require the business to hold its breath. Every one of these projects I have seen finish, finished this way.

What the audit produces

A useful audit hands over four things:

• A map. What exists, what talks to what, and where the data lives. Most firms have never had this on one page.
• A risk register. Ranked by business impact, not by code smell. What breaks, what it costs, how likely it is.
• A sequence. What to do first, what that unblocks, and what can wait indefinitely.
• A number. Against that sequence, phase by phase, with the assumptions written down.

If an audit produces a document that says the code is bad and should be rewritten, you have paid for an opinion you already had.

The thing to check before anything else

Access. Before assessing a line of code, confirm you control the repository, the hosting, the domain registrar, the database, the deployment pipeline and the third party accounts the system depends on.

I have seen firms discover, in the middle of a modernisation, that their production database was in a personal account belonging to a contractor who left in 2021. Code you can read is a manageable problem. Infrastructure you cannot reach is an emergency, and it is worth ten minutes of checking before anything else begins.

Where this leaves you

Most inherited systems are in better shape than the people who inherited them believe. What is usually missing is not quality but comprehension: nobody has read the whole thing recently and written down what they found.

That is a few weeks of work and it changes the conversation from an anxious one about rewriting to a specific one about sequence and cost. If you want that done properly, with a plan you own whether or not I build anything, that is an MVP Roadmap.