How I learned to ship in codebases I didn't write

My first week at Enigma, I was handed a Django codebase I had never seen, in a stack I had never used, with a feature request and a deadline. There was no onboarding document. No one walked me through the architecture. There was just the code and the expectation that I would figure it out.

I did. And over the next nine months I did it five more times — each time a different codebase, a different framework, a different domain. Here is the method I arrived at.

Make it run first

Before you read a single line of application code, make the project run locally. This sounds obvious and it is often harder than it sounds. Find the entrypoint. Install the dependencies. Get something to print to the terminal.

Until the application is running you are reading code in the abstract. Once it is running, every line has a consequence you can observe.

Read the models

The data model is the skeleton of the application. Everything else — the routes, the views, the signals, the admin — is built on top of it. Read the models first and you will understand the domain. You will know what a Subscription is, what a Delivery is, how they relate to an Order, and why there is a set rather than a single record. The rest of the code makes sense faster.

Follow one request

Pick a feature you understand — a login, a form submission, a list view — and follow it from the entry point to the response. Read every function it calls. Don't skip the ones you don't understand immediately. Pause on them.

One complete request path, read carefully, teaches you more about how a codebase is organised than two hours of reading files at random.

Make a small change

Find the smallest change that is safe to make and make it. A missing field in an admin display. A computed property that should be exposed. An error message that is wrong. Something small enough that you are confident you understand the consequences. Commit it.

Nothing builds familiarity with a codebase faster than having your change reviewed by someone who wrote it.

Ask about decisions, not facts

When you have a question, ask about why a decision was made, not what a thing does. "What does this do" is a question you can answer by reading the code. "Why was this done this way instead of the obvious alternative" teaches you how the people who wrote it think. Those answers make every subsequent decision faster.

The thing I was not expecting

The hardest part of working in an unfamiliar codebase is not understanding the code. It is resisting the urge to rewrite what you don't immediately understand.

Almost everything that looks wrong on first reading is either doing something you haven't understood yet, or was written under a constraint you don't know about. Read it twice before you decide it needs to change.