Reading & Reverse Engineering Code

An unfamiliar codebase: entry point, follow the data, find the state, find the side effects, understand the boundary. Not "read every file".

Reading a Codebase

README, entry point, one main feature end to end, the dependencies it pulls in, the data model it touches, and the tests that describe it — in that order, and stopping when the question you came with is answered. Not every file.

Q · You have just been given access to a repository you have never seen and a task inside it. Where do you start reading, and when do you stop?
Debugging Code You Did Not Write

Find the entry point, follow the data, find the state, find the side effects, understand the boundary. Five questions that turn an unfamiliar failing system into a path you can put observations on — without first understanding all of it.

Q · Something is failing in code you have never read and there is no time to learn it all. What do you find first, and in what order?
Reverse Engineering a System

Where does the program start? What receives input? Where is data stored? Which modules change state? What external systems exist? Five questions recover the design of a system whose design was never written down — from the running thing, not the folder names.

Q · You have inherited a system with no documentation and no author to ask. How do you recover what it is and how it works, without reading all of it?
Follow the Data

Pick one value — an order, a price, a cart — and follow it from where it enters to where it rests, through every transformation and hand-off. Code is organised by module; behaviour is organised by data, and following the data reads the code in the order it actually runs.

Q · You need to know what happens to a piece of data between the request and the database, and the code is spread across a dozen files. How do you read it in the order it runs?
Before You Copy Code

A snippet from documentation, a search result or an assistant is a proposal, not a solution. Before it goes in: what does it do, why does it work, what does it assume, and how does it fail? Four questions that take minutes and are the difference between using a tool and being used by it.

Q · You have found code that appears to do what you need — in the docs, a forum, or an AI answer. What do you establish before pasting it into the store?