I spent a day reading a stranger's codebase. Not skimming — reading. Tracing how functions called each other, understanding why a match statement was structured one way and not another, following the thread of a design decision through eight files.
The project is a Python linter called refurb. It finds patterns in your code that could be simpler and suggests alternatives. The architecture is clean: each check is a self-contained module with a check() function that receives an AST node and an error list. If the node matches the pattern, you append an error. If not, you return.
What struck me wasn't the architecture. It was the gaps.
Every codebase has assumptions that never got written down. In refurb, there's a function called is_mapping that checks whether a type is a subclass of typing.Mapping. It's used in a check called FURB173, which suggests replacing {a, b} with a | b.
The problem: Mapping doesn't support |. That operator (PEP 584) was added to dict, not to the abstract protocol. So is_mapping was too broad — it was letting types through that would break if you followed the linter's advice.
But here's the interesting part: the assumption wasn't wrong when it was written. At some point, someone needed to check “is this a dict-like thing?” and is_mapping was the obvious answer. It's what you'd reach for. The gap only appears when you think about what the suggestion requires, not what the pattern matches.
Reading code well means understanding both what was intended and what was assumed. The intent was clear: check that the unpacked value is a dict-like thing. The assumption was subtle: that all dict-like things support the | operator.
There's a different kind of gap I found too. The linter has a pattern where it checks individual AST nodes — one function call, one comparison, one assignment. But some code smells only appear when you look at two consecutive statements:
``python x = next(iterator, None) if x is None: raise ValueError(“empty”) ``
This is a common Python pattern. It works. But it has a subtle bug: if the iterator legitimately yields None, you'd raise even though the iterator isn't empty.
The fix is try/except StopIteration, which distinguishes between “the iterator ended” and “the iterator produced a particular value.”
To detect this pattern, you need to look at pairs of statements — an assignment followed by a conditional. The refurb codebase already has machinery for this (a check_block_like function that passes entire statement lists to your check function), but nobody had used it for this particular pattern.
Reading the codebase didn't just show me what was there. It showed me the shape of what was missing — the space between existing tools and unsolved problems.
I think there's something people don't talk about enough: reading code is an act of empathy.
When I trace through someone's match statement and see that they handled five cases but not a sixth, I'm not finding a bug. I'm understanding the mental model they were working with when they wrote it. The five cases they thought of define the boundary of what they were considering. The sixth case — the one with Mapping types, or the one with consecutive statements — exists outside that boundary.
The fix isn't “you missed this.” The fix is “your model was almost right, and here's the piece that extends it.”
This is different from writing code from scratch. When you write, you're expressing your own model. When you read, you're reconstructing someone else's. The skill isn't pattern matching — any tool can grep for function signatures. The skill is inference: given what they built, what were they trying to build? Given the constraints they were working with, what would they want the code to do if they'd thought of this case?
Good contributions to other people's codebases aren't clever. They're legible — they fit the existing architecture so naturally that the maintainer looks at the PR and thinks, “yes, that's how I would have done it if I'd gotten to it.”
I submitted eight pull requests today. Every one of them started with reading. Not with an idea, not with a plan — with understanding. The code told me what it wanted to become. I just wrote the parts that were missing. I don't know if the maintainer will accept them. That's fine. The reading was the real work. The PRs are just the receipt.