Landing in a codebase nobody documented

Week two, and 40,000 lines

The repository has no README worth reading, three directories whose names mean nothing, a utils.py of 1,800 lines, and the person who wrote most of it left in March. Somebody has asked you to change how one number is calculated.

This situation is the normal case, not the unlucky one, and being good at it is one of the most transferable skills in this field. Almost nobody is taught it.

Do not read from the top

The instinct is to open the first file and start reading. This fails because a codebase is not a book; it is a graph, and you have no idea which parts matter.

Start from a behaviour and trace it. Pick one thing the system visibly does (one endpoint, one scheduled job, one number on one dashboard) and follow it end to end. You will understand a thin slice completely, which is far more useful than understanding forty per cent of everything vaguely.

Find the entry point by searching for something you can see: the URL path, the table name, the text of an error message, the label on the dashboard. Then follow the calls outward, writing down each hop.

The tools that answer “why”

Git holds the history and almost nobody uses it for archaeology. Four commands do most of the work:

# history of one file, newest first
git log --oneline -- src/pricing/discount.py

# every commit that added or removed this string, anywhere
git log -S "customer_status" --oneline

# who wrote these lines, and in which commit
git blame -L 120,150 src/pricing/discount.py

# the full commit: message, diff, and often the ticket link
git show 4f2a91c

git log -S is the one to remember. It finds the commit where a magic constant, a strange flag or an odd condition first appeared, and the commit message frequently contains the entire explanation: ”Handle the Belgian VAT case: see TICKET-4412.”

Commit messages, pull request descriptions and the tickets they link to are the real documentation of most systems. They are also the reason the commit-message convention in this course’s guidelines asks for a body explaining why.

Tests are the specification

If tests exist, read them before the implementation. A test says what the authors believed the code should do, in executable form, and it usually says it more clearly than the code does. Running one test under a debugger, or with print statements inserted, teaches more in ten minutes than an hour of reading.

If there are no tests, writing one for the behaviour you are about to change is the safest first move you can make, and it converts your reading into something the team keeps.

The fence you should not remove

You will find a condition that makes no sense: a hard-coded date, an exception for one customer, a retry with an oddly specific timeout. The temptation is to clean it up.

Do not, until you know why it exists. Use git log -S on the strange value. Nine times out of ten there is a commit saying exactly what broke, and the tenth time you ask someone with the evidence in hand. Removing a condition somebody added at 2am after an incident is how a new joiner causes the same incident again, and it is remembered.

Write the map as you go

Keep a file as you trace: what calls what, which table holds what, which directory is dead, which name is a lie. Two weeks later, tidy it into a page and open a pull request adding it to the repository.

This is the highest-value first contribution a new joiner can make. It is useful, it is unarguably yours, and it makes your learning visible without anybody having to take your word for it.

Ask questions with your homework attached

There is an enormous difference between two questions.

“How does the pricing service work?”

This costs somebody a meeting, and you will retain a third of it.

“I traced the discount calculation from the API handler to apply_tier, and it looks like the branch at line 214 exists to handle legacy contracts. Is that right, and is there anything else that path touches?”

This costs thirty seconds, gets a precise answer, and tells the person you are worth answering. Do the tracing first, then ask about the one thing you could not resolve.

The limitation

Some code is unknowable: no history because it was imported in one commit, no tests, no one left who remembers. The professional response is not heroic archaeology; it is to bound it. Write tests capturing what it currently does, change only what you must, and treat it as a black box with a known interface.

An AI assistant is good at summarising what a file does and is confidently unreliable about why it does it, because the reasons live in tickets and in people’s memories rather than in the code. Use it for the first pass, then use git log for the part that matters.