Inheriting a codebase: what the first week should tell you

The instinct on receiving an unfamiliar system is to open the code and start reading. A better first move is to measure a small number of things that predict how the next year will go — most of which live outside the source files, in the repository history, the deployment pipeline and the issue tracker.

This is the sequence we run on a paid audit, compressed into something you can run yourself with a competent engineer and five days. It works equally for a system inherited from a vendor, acquired with a company, or left behind by a departing team.

Day one: can it run, and can it ship?

Two questions answered on the first day tell you more than a week of reading.

How long until a new engineer has it running locally? Time it honestly, from a clean machine. Under an hour indicates a team that valued the on-ramp. A day is common and manageable. Longer than that is the first thing to fix, because it multiplies the cost of every future hire and every future contractor.

How does a one-line change reach production? Make a trivial edit and follow it all the way. What you learn: whether there is a pipeline, whether tests run, whether a human reviews, whether a rollback exists, and how long the round trip takes. A system where this takes twenty minutes and one approval is in good health regardless of what the code looks like.

Day two: what the history says

The repository history is the most candid document in any handover, because nobody writes it for an audience. It answers questions that no meeting will.

• Who actually wrote this system. Commit distribution across authors, over time. If 80 per cent came from one person who has left, that is the single most important fact about your position.
• Whether review happened. The proportion of changes that arrived through a reviewed pull request, and whether the reviews contain substance.
• Real velocity. Changes per week over the last year, and how it trended. A slow decline usually means the system became harder to change.
• Where the churn is. Files edited far more often than the rest. These are either the heart of the product or the part nobody got right, and it is worth knowing which.
• Whether tests grew with the code. Test files added alongside features, or in occasional bursts long afterwards.

An afternoon with standard repository tooling produces all five. In our own audits this section is often the one clients find most useful, because it describes the delivery process that produced the code — and that process is what you are inheriting along with it.

Day three: the data model

Of everything in a software system, the data model is the most expensive to change later and the most informative about the quality of thought that went in.

• Is there a migration history? A versioned, ordered set of migrations means the schema can move safely. Its absence means schema changes have been manual, and the environments have probably drifted apart.
• Are the constraints in the database? Foreign keys, uniqueness, non-null. Rules enforced only in application code are rules that hold until the second application arrives.
• Does the shape match the product? Read the main tables and see whether the product’s concepts are visible in them. Where they are, the system will accommodate new features. Where the product has moved on and the schema has not, that gap is the real backlog.
• What is the volume, and what is the growth? Table sizes and their trend decide whether the current design has years left or months.

Day four: the operational surface

Now look at what happens while nobody is watching.

Each row that is missing has a known cost and a short remedy. Together they usually amount to one to three weeks of work, and they are almost always the highest-value weeks available.

Day five: turn it into a plan

Findings become useful when they carry a cost, an effect and an order. Sort everything you have into four groups.

1. Now. Anything where an incident would be both likely and expensive: exposed credentials, absent backups, missing authorisation. Days of work.
2. Soon. Things that make every subsequent week cheaper: the local setup, the deployment pipeline, tests around the paths that carry money and data. Weeks of work, and they pay back inside the quarter.
3. Planned. Data model changes, dependency upgrades, the architectural work the product now needs. Months, scheduled deliberately alongside features.
4. Noted. Things that are imperfect and harmless. Write them down and leave them alone. A plan that proposes fixing everything is a plan nobody funds.

Then put a number against each item and a sentence on what it changes. A list of twelve findings with costs and effects is something a board can approve. A list of forty observations is something that gets read once.

What we hand over on an audit

Our code and developer audit runs this sequence with two engineers and returns a written report in three days: the state of the code, what the repository history says about the delivery process behind it, the operational picture, and a costed plan in the four groups above. It needs read-only access and nothing is run against your live systems.

Clients use it in three ways. Before an acquisition, as technical diligence. During a vendor transition, as an independent statement of what is being handed over — written professionally enough to share with the outgoing team. And as a planning document, when a product has been running for years and the roadmap needs a foundation everyone agrees on.

Sometimes the report says the system is in good order. That is a useful outcome too, and it is worth the same to a board as a list of findings.

One thing worth remembering

Inherited systems tend to look worse from the outside than they turn out to be. Unfamiliar code reads as poor code for the first week, and then stops. The measurements above exist to separate the genuine constraints from the unfamiliarity — and in most engagements we take on, the honest answer after five days is that the system is workable, three things need attention quickly, and the roadmap can start next month.