productivity / best-practices / code-review

The Art of Reading Someone Else's Code

You spend more time reading code than writing it. Here is how I approach an unfamiliar codebase without drowning in details.

2 min read
Cover image for The Art of Reading Someone Else's Code

The Art of Reading Someone Else's Code

Most advice about code is about writing it. But you spend way more time reading code than writing it. Especially code written by someone else who is not around to explain it.

I used to open an unfamiliar codebase, find the first file, and read from top to bottom. That is a bad strategy. You end up buried in utility functions and type definitions before you see anything that does real work.

A better approach is to find the entry point first. That is usually main or index or the route handler. Read just enough to understand what modules the system loads. Then trace one feature from the request to the response. Do not worry about the other features yet.

The second thing I do is look at the test files. Tests often reveal what the author thought was important. If there is a test called handles_rate_limiting or paginates_when_many_results, that tells you what the system does better than reading the implementation first.

Third, I rename things in my head as I read. If a variable is called data and it is actually a user record, I keep a note that data means user in this file. Good naming is rare. Do not fight bad names. Just translate them.

A lot of people ask about understanding the codebase architecture without reading every file. You cannot skip reading. But you can read strategically. Read the interfaces and the tests first. Then read the parts that the tests exercise. Then read the error handling paths. By that point you have a map of the system and you can fill in the details only when you need them.

I also keep a running document of questions when I am exploring a new codebase. Why does this module exist? What would break if I deleted it? Why did they use a factory here instead of a constructor? Some of those questions get answered as I read more. The ones that stay unanswered are usually worth asking a teammate about, because they point to design decisions that are not obvious from the code alone.

Keep reading
Cover image for Why I Reach for Map Over Object in JavaScriptjavascript

Why I Reach for Map Over Object in JavaScript

Plain objects have prototype quirks and limited key types. Map handles dynamic collections more cleanly and eliminates a whole class of bugs.

Cover image for What I Learned Debugging a Node.js Memory Leaknodejs

What I Learned Debugging a Node.js Memory Leak

A service was crashing every three days with memory climbing to 1.5 GB. The leak turned out to be in a trusted dependency, not our own code.

Cover image for CSS Container Queries Are Finally Herecss

CSS Container Queries Are Finally Here

Container queries let you style elements based on their parent size instead of the viewport. After years of waiting, they are finally ready for production.