What I look for in a codebase review

I get asked to review codebases for startups, and it's often the first week of a bigger job. Founders usually expect me to come back talking about code style. I almost never do. Style is the cheapest thing to fix and the least likely thing to kill you. Here's what I'm looking for instead.

The corner everyone avoids

Every codebase past a certain age has one: the module nobody touches, the file with a comment saying do not edit, the job that runs at 3am and nobody knows why. I go there first. Not because it's fun, but because that corner is where the risk lives. If the team is routing around a piece of their own system, the product roadmap is quietly routing around it too.

The question isn't whether the scary corner exists. It's whether anyone can explain it, and what the plan is if it stops working on a Saturday.

Can the history tell the story?

Version control tells you more about a team than any interview. I look at how work ships: branches, reviews, releases, and whether the history reads like a story or a panic. If I can't work out from the repo how a change gets from a developer's head to production, then neither can the next person you hire, and every release is being carried in someone's memory.

The simplest test I know: if a laptop died tonight, what would be lost? The answer should be nothing and a shrug. It often isn't.

Who holds it up?

The bus factor, politely. Who set up the server. Who knows how deploys work. Who has the passwords, and where. In a lot of businesses I review, the answer to all three is the same name, and everyone in the room already knew it before I said it out loud. Writing that down isn't an insult to that person. It's a gift to them: they get to go on holiday.

What I don't do

I don't grade style, I don't count spaces, and I don't recommend a rewrite by default. A rewrite is usually the expensive way to avoid understanding something. Most of the codebases I see don't need replacing. They need the risks named, the knowledge written down, and two or three specific things fixed in the right order.

What comes out the other end

A written report. Plain English up front, so the board can read it without a translator, and the technical detail attached, so the team knows I actually read the code. Findings in priority order: what's solid, what's fragile, what to fix first, and what it costs to ignore. If the codebase is fine, the report says so. That happens more often than people expect, and it's a good day when it does.

The full scope of what I look at, including infrastructure, backups and disaster recovery, is on the Technical Review page. It starts, like everything, with a free 30 minute call via the contact page.