Code reading notes

Reading a new codebase is mapmaking. You start at the doors (where execution begins), follow one real request or command through the building, and sketch the rooms you pass. Notes made this way are worth keeping, because the picture fades within days and the next person to join will need the same map.

These notes are not documentation of everything. They record what a reader learned, in the order that made sense of it: where it starts, how the parts connect, the few types everything else depends on, the house conventions, the things that surprised you, and the questions only the team can answer.

When to use it

• A developer is new to a team or repo and wants to get oriented.
• They need to change a part of a system they did not write.
• They are evaluating an open-source library before depending on it.
• They are reviewing a large pull request and need the surrounding context.
• They have a folder tree, some files, or rough notes and want a map.