Why It Feels Hard
Reading code you didn't write is uncomfortable for a straightforward reason: you don't have the mental model the author had when writing it. You're reconstructing something from artifacts — variable names, structure, comments (if you're lucky) — without being able to ask the original question: "What problem were you solving?"
The discomfort is normal. The goal isn't to avoid it; it's to move through it faster.
Start From Behavior, Not Structure
The worst way to read a codebase is to start at main() and read linearly. You'll drown in detail before you understand anything.
Start from behavior:
- What does this thing do from the outside? Run it. Call the API. Observe the output.
- Find the entry point for the specific behavior you care about. Often this is a route handler, an event listener, a public method.
- Read just that path. Resist the urge to explore.
The Annotation Technique
As you read, add comments. Not for anyone else — for yourself. Paraphrase what each function does in plain language. Note what you don't understand with a ?. Mark assumptions you're making.
This does two things: it forces active engagement (you can't mindlessly scroll), and it gives you something to refer back to later.
Follow the Data
When understanding how something works, trace a single piece of data through the system. Pick a value — a user ID, a request body, a message — and follow it from input to output. What transforms it? What validates it? Where can it go wrong?
This is more revealing than reading the code structurally because it shows you what actually matters.
Accept Partial Understanding
You don't need to understand everything before you can contribute. The goal is "understand enough to change this specific thing safely," not "understand everything."
The best engineers in legacy codebases are comfortable saying "I don't fully understand this module, but I understand enough to make this change and I know what to test." That's a legitimate position.
The Investment Mindset
Every hour you spend reading code that wasn't written by you is an investment. The next time you work in that area, you start 20 minutes ahead. The time compounds.
The engineers who are most effective in large codebases aren't the ones who've memorised it. They're the ones who've read it enough to know where to look.