Picking up someone else’s codebase: the first two days

You’ve got a website that’s nearly finished. The person who knew it best has moved on, and now someone new has to pick it up. Nobody’s quite sure where to start.

Don’t worry. That’s a really common place to be, and it’s very fixable.

Before I change a single line of someone else’s code, I spend two days getting to know it. No commits. No estimate. Just running it, reading around it and making notes.

It can look like nothing much is happening. It’s actually the most useful part of the job, because the costly mistakes in picking up a stalled build tend to happen in the first week, when there’s pressure to be seen doing something.

Why the build actually stopped

It’s rarely because the work was hard.

Usually the person who understood it moved on, not much got written down, and nobody wants to be the first to touch it. That last part is the real blocker, and it’s more about people than code.

Picking up a half-finished build is uncomfortable for anyone. You’re slow for a week. You ask questions that sound obvious. You might break something that was working. It can feel like everyone is watching.

So the work waits. Not because it’s hard, but because starting means a slow, awkward couple of weeks, and that’s a tough thing to volunteer for on a project that’s already late.

That feeling is completely normal. It happens to everyone who picks up someone else’s work, me included.

It’s also why bringing in someone from outside can help. Being slow for the first week is simply part of the job I’ve been asked to do, so nobody has to feel awkward about it. The slow week passes, and the project starts moving again. If you’re an agency rather than the business that owns the site, the three ways that arrangement usually runs are worth deciding on before the first client call, because it changes who answers their questions while all this is going on.

The first two days

Get it running locally, map the surface rather than the code, find what is load-bearing, then write the honest report. The estimate comes only after all four.

Hours 1–4: get it running locally

Before forming any view of the code. Before any estimate.

The goal is one thing: the application running on my machine, doing something. Everything I learn on the way there goes into my notes.

• If the README is out of date, that’s the first thing to note. READMEs drift, and that’s normal. Write down where it differs from what actually happens. The gap tells you roughly when the project stopped being actively maintained.
• Each missing environment variable tells you something. Every one I have to ask for is a third-party service the site depends on, and together they’re often a more complete list than any architecture document.
• How long it takes to get running says a lot about the handover. A few hours is a fair expectation. If it takes two days, the handover was probably light on detail, and that’s worth mentioning to whoever is paying, early and kindly.

I don’t fix anything yet, even the tempting bits. A fix on day one is made without the full picture.

Hours 4–8: map the surface, not the code

The first question is what the site touches, rather than everything it contains. That’s a much shorter list, and a more useful one.

Three lists, none of them long:

Every route a human can reach. Pull them from the router, the CMS, the sitemap, whatever is authoritative. Then open a representative sample in a browser. Pages that quietly throw an error are often where the unfinished work is.

Every third party it calls, and what breaks without it. Payment, email, CRM, search, maps, analytics. For each one: does the site degrade or does it fall over? A build that stops working when an analytics service is slow carries more risk than one that carries on without it.

Where the data lives, and who else writes to it. A database another system also writes to is a very common reason something “works on staging” and not on the live site. It often doesn’t get mentioned, simply because to the people there it’s just how things work.

Reading the code line by line can wait. An hour on these three lists usually tells you more about the risk than a week of reading.

Day 2, morning: find what is load-bearing

Most inherited codebases have one piece everyone is a bit nervous of. It’s much better to find it early, on purpose, than at six o’clock on a Friday.

You can usually spot it without fully understanding it:

• The file with the most recent commits and no tests. Lots of change with no safety net is where the risk tends to sit.
• The function every other file imports.
• Anything with a comment beginning “don’t”, “careful” or “temporary”.
• Anything someone was part-way through when they moved on.

git log answers most of this faster than reading does. A file that has been changed forty times in two years is telling you something that the code itself will not.

The point is not to fix it. The point is to know where it is before you accidentally lean on it.

Day 2, afternoon: the honest report

Two pages, sent before any quote.

It separates out three things that are easy to lump together:

What is genuinely risky. Things that will cause an outage, lose data, or block launch. These need fixing and I will say so plainly.

What is just a matter of taste. Code I’d have written differently, but that works fine. This is only worth spending money on if you want to, and most of the time you don’t need to. Anyone new to a codebase will find plenty in this category, me included, which is exactly why it’s worth keeping separate. Otherwise a preference can end up sounding like a risk.

What I couldn’t work out yet, and what it would take to. The honest unknowns, each with a cost to resolve. After two days there will always be a few of these, and that’s normal.

The honest report

Three separate lists, so you can see straight away which parts actually need your budget. Anyone new to a codebase will find plenty in the middle column, which is exactly why it is worth keeping separate.

Then, and only then, an estimate. Before this point, any number would really just be a guess.

Why I rarely suggest a rewrite

Starting again from scratch can feel like the tidy option. It’s easy to explain, and it’s much easier to picture than “let me spend three weeks understanding this”.

It’s also usually far more expensive than it looks. The existing code already handles lots of small things nobody wrote down, and a rewrite means finding every one of them again. That’s a big part of why rewrites so often run past their first estimate.

Sometimes the platform really is at the end of its life, and a rewrite is the right answer. When that’s true, I’ll say so plainly. It just comes up less often than you might expect.

Most of the time the build is roughly fine, and what it needs is someone happy to take a slow couple of weeks to understand it. What is usually left is not the hard part either: it tends to be the last ten percent, the error states, the empty screens and the admin jobs nobody ever demos.

If the project also has the wider symptoms of a delivery problem, the code was probably never the reason it stalled.

How I do this one

This is the work, not a description of it.

• Two days first, then a number. You get the written report either way, and if you decide to take it somewhere else, it is yours to hand to whoever you take it to.
• By the day to begin with, because finishing a stalled build only becomes clear once I am in the code. Once it is clear, the rest can become a fixed price.
• I work inside what is already there. Your platform, your patterns, your half-finished build. If a rewrite is genuinely the right answer, you will hear why before you hear a price.
• Whatever happens, it ends with a handover, so the next person, me or anyone else, does not have to do these two days again.