The first time you open a repository that is not yours, the instinct is to start reading files. Top to bottom. It feels productive for about four minutes, and then you close the tab, because nothing sticks.
The problem is not the code. The problem is that reading a program is not reading a text. A text tells you what it means. A program tells you what it does right now, and everything else why it is shaped that way, what used to be there, which of these five similar-looking functions actually runs is not written anywhere in the file you have open.
Reading code is a skill, and like the rest of them it has a method. This is mine: run it, enter it, follow one path, break something.
Why this matters more than writing
You will spend more time reading code than writing it. That is not a motivational phrase; it is arithmetic. Every change you make starts with understanding the surrounding code, every bug starts with finding the code that lies, and every review is reading.
Writing is a small fraction of the job. And yet every course, every tutorial and every book teaches you to write, and almost nothing teaches you to read. So people improvise, and the improvisation is "open files until something clicks", which works, eventually, at the cost of days.
A junior who can read unfamiliar code has a superpower that requires no permission: any repository on Earth is available today, for free.
The method
Four steps, in this order. The order is the point.
1. Run it. Before reading a single line.\
2. Enter it. Find the door and look at nothing else.\
3. Follow one path. End to end, ignoring the other 95%.\
4. Break something. Change one value and watch what screams.
And a fifth that is not a step but a habit: ask the history.
I will use a real repository to show each one: serverctl, a Go TUI for administering Linux servers over SSH. 107 Go files under internal/, split across ui, core, collectors and actions, plus the entrypoint in cmd/. That is enough code to get lost in, which is exactly why it is a good example.
Step 1: Run it
Before you read the code, make the program work. Clone it, build it, execute it.
git clone https://github.com/felipecastillo-b/serverctl.git
cd serverctl
make build
./bin/serverctl
This sounds like a detour and it is the single highest-value step. A running program answers questions the source code cannot: it tells you which of these features are real, which screen opens first, what happens when a file is missing, and where the output comes from.
It also builds the vocabulary. In serverctl you press a key and see a dashboard with CPU, memory, load and uptime; you press tab and you are in processes; you press ? and a help overlay appears. Now you know what the words mean before you meet them in the code.
If the build fails, do not skip ahead. Fixing the build is the first real exercise in reading the project: the error names a version, a dependency, or a missing header, and that is the first true thing you have learned about how it is put together.
Step 2: Enter it
Every program has a door. In Go it is main, and by convention it lives in cmd/<binary-name>/.
Open exactly one file: cmd/serverctl/main.go. It is 72 lines, and those 72 lines describe the entire shape of the program:
- flags:
-versionand-config -
config.Load(path)to read YAML, with defaults when the file is missing -
keys.DefaultGlobal()andglobal.ApplyOverrides(cfg.Keys)to apply your keybindings -
screens.ValidateScreenKeys(cfg.ScreenKeys)to reject invalid ones - one line that starts everything:
tea.NewProgram(app.New(cfg), tea.WithAltScreen())
That is a compressed map of the application. Config is loaded first, validated before the terminal takes over, and then handed to a single model that owns the interface.
Do not read the rest of the code yet. You now know where the program starts and what it needs to start. That is enough for step three.
Step 3: Follow one path
Now pick one thing the program does and trace it from the door to the kernel, ignoring everything else. One path. Not all of them.
Take the dashboard. From step two, you know it is created by app.New(cfg). Open internal/ui/app/app.go. The comment at the top says what you would have guessed by now: it hosts the sidebar, the active screen, the refresh ticker, the keymap, the mouse input, the help overlay and the command palette.
That is still too big. Go narrower. The dashboard needs CPU numbers. Where do they come from?
This is the moment the method pays for itself. In serverctl, internal/core/ports.go defines interfaces: UnitLister, JournalReader, StorageLister, ContainerLister and friends. The UI depends on those interfaces, not on /proc. The things that implement them live in internal/collectors/, and the things that change the system live in a separate package, internal/actions/.
So the path is: screen asks a port, a collector implements it, the collector reads /proc or D-Bus, the data comes back as a typed struct.
You have just learned the architecture from the outside in, by following one number, instead of memorizing a diagram. And now the interface names make sense, because you needed one of them.
This is also how you read a repository with 107 files: you do not read 107 files. You read five, and you learn that the other 102 follow the same shape.
Step 4: Break something
Change one thing and observe the failure. This is faster than reading the code that handles it.
In serverctl, the config file lives at ~/.config/serverctl/config.yaml and accepts a keys section. Do this:
keys:
quit: ctrl+q
Then change quit to something invalid — quit: notakey — and start the program. It refuses to open the interface and prints a readable error, before it ever takes over your terminal. That tells you something no amount of reading would have made obvious: validation happens before the alternate screen starts, deliberately.
And the source says exactly that, in a comment right above the call, explaining that app.New trusts the values are valid so they must be checked first. You earned the comment by breaking the thing it protects. That is the difference between having read it and having learned it.
Break things on purpose. Delete a file the program expects. Pass a flag with a wrong value. Point it at a path that does not exist. Every failure is a free lesson about how the code is ordered, and order is the part of a codebase that documentation never captures.
The fifth habit: ask the history
The code tells you what exists. The history tells you what was tried and removed.
serverctl's README has one line that is a small essay on its own: version 0.5.0 shipped SMART disk health, and version 0.5.1 removed it, because SMART reads require root or a raw I/O capability, and the whole project refuses to escalate privileges.
Nobody reading the current source would find that. The feature is gone. The reason is gone with it. It survives in a changelog and in git log.
So when something looks strange — an empty function, a configuration option nobody uses, a TODO from two years ago — do not assume the author was careless. Ask:
git log --oneline -- path/to/the/strange/file
git blame path/to/the/strange/file
Nine times out of ten, the strange thing is a scar. The tenth time it is genuinely bad code, and now you have evidence instead of an opinion.
Draw five boxes
When you finish, close the editor and draw the program on paper. Five boxes, arrows between them, no detail.
For serverctl mine would be:
-
cmd/serverctl— flags and wiring -
internal/ui— models, screens, sidebar, palette -
internal/core— domain types and the ports the UI depends on -
internal/collectors— read-only adapters over/proc,/sys, D-Bus -
internal/actions— the only package allowed to change anything
If you cannot draw it, you did not understand it; you memorized it. And memorized code disappears in a week.
The repository already has this map in ARCHITECTURE.md, with a layer table and a module table. Using existing documentation is not cheating, it is the fastest legal move. But verify it against the code: documentation ages, and the one thing worse than no map is a map of a city that was demolished two releases ago.
Three ways to do this badly
Reading breadth-first. Opening thirty files in ten minutes feels like progress and produces nothing. Depth over coverage, one path at a time.
Reading without running. You are reading a description of a program, written in a language designed for machines. Run it, or you are doing literary criticism.
Judging before understanding. "This is badly written" almost always means "I do not know why it is like this yet". That line in main.go that ignores an error and discards it with _, _ = looks careless — until you read the comment explaining that the linter requires an explicit decision and there is no recovery if writing to stderr fails. Two lines of context change the verdict completely.
Try it this week
- Pick a repository you already use and have never read. Any size.
- Run it, enter it, follow one path, break one thing.
- Draw the five boxes.
- Write one paragraph: what would break if you deleted the file at the center of the path you followed.
That paragraph is worth more than ten tutorials, because it is the only proof that you actually understood something.
The last thing
Nobody is going to give you permission to read a codebase. There is no onboarding for the repository you are curious about, no ticket, no reviewer. It is just there, and you can open it.
That asymmetry is the best deal available to a junior: the most senior engineer in the world has exactly the same access to that source as you do, today, for free. Reading it is a skill you can start practising in the next five minutes.
I wrote about how programmers think before. This is the other half: thinking is what you do once you can read.
Top comments (0)