Reading Source Code: How I Do It Without Going Insane
TL;DR: Source code is the highest-density learning material in our field, and almost nobody teaches you to read it. Here's the technique that turns 'overwhelming' into 'tractable.'
Start with the entry point
Open package.json or pyproject.toml. Find the main or scripts.start entry. Open that file. Read top to bottom. Don't follow every import yet — just get the shape.
After 30 minutes of doing only this, you'll know more about the codebase than 80% of contributors do.
Follow one feature, end to end
Pick one user-facing feature. Trace it from the UI (or API request) all the way to the database. Don't try to understand everything; understand this one path completely.
When you're done, pick the next feature. Two or three of these and you'll have a mental map of the whole system.
Read tests when the code is unclear
Tests are usage examples. If a function's behavior isn't obvious from its source, the test file usually has the answer. git grep 'function_name(' --include='*.test.*' is your friend.
git log -p on a single file
When a file looks weird, run git log -p path/to/file.ts. The recent commits show what's been changing and why. Often a 50-line function makes sense once you see it grew from 5 lines over three years.
git log -p --follow src/payments/refund.ts | less
# or, see who introduced a specific line
git blame src/payments/refund.ts | grep "weird thing"
git show <commit-sha>Commit messages and PR descriptions
Good repos document context in commit messages and merged PR descriptions. gh pr list --search 'merged:>2024-01-01' --json title,url,body dumps recent PRs. Read 20 of them before reading any code.
When to give up
If a codebase is genuinely undocumented, untyped, and the original authors are gone — sometimes the right move is to stop reading and start rewriting from the outside. Read the public API, write a clean replacement, throw away the old code.