Reading unfamiliar code

Read with questions

Nobody reads a phone book from front to back. You look up the name you need. Reading code without a goal is slow and forgettable too. Ask a question ("where do prices get rounded?"), find the answer, and move on. Keep a notes file of what you learn: it becomes the docs the next new person wishes they had.

In plain words: start with a question and read until it's answered, not from line 1 of file 1.

Maps from code

Python can read its own source as a tree with the ast module, a bit like diagramming a sentence into its parts. That makes custom maps easy: every function and class with its line, which functions call which, and which functions nothing calls. Real tools work the same way: linters, editors and code search all parse code into trees.

ast.walk(node) visits every node inside a tree. A call like total(items) is an ast.Call whose func is an ast.Name with id "total". A call like cart.total() has an ast.Attribute instead, which is harder to resolve without running the code. That's why static maps are a guide, not the full truth. A road map shows the roads, not where the traffic actually goes.

import ast

source = """
def load(): return read()
def read(): return 1
def save(): return 2
def main(): return load()
"""

calls = {}
for node in ast.parse(source).body:
    if isinstance(node, ast.FunctionDef):
        calls[node.name] = [n.func.id for n in ast.walk(node) if isinstance(n, ast.Call)]

print(calls)
called = {name for targets in calls.values() for name in targets}
print("nothing calls:", sorted(set(calls) - called))

import ast

source = '''
def load(path):
    return parse(open(path).read())

def parse(text):
    return text.split(",")

class Cart:
    def add(self, item):
        pass
'''
tree = ast.parse(source)
for node in tree.body:
    print(type(node).__name__, node.name, "line", node.lineno)

import ast

tree = ast.parse("class A:\n    def f(self): pass\n\ndef g(): pass\n")
print([type(n).__name__ for n in tree.body])

You don't have to read it all

Trying to read a big codebase from start to finish is a trap. It's slow, and most of it won't stick, since you have no reason yet to care about any of it. Reading with a question works far better. Start from something real: a small bug, or a question such as "what happens when someone clicks Buy?". Then follow that one path. Your understanding grows outward from there, and you remember it because you used it.

Run it before you read it

You learn more from one test drive than from the manual. Running the code tells you so much that it's worth doing first, even if setup takes an hour. You learn what it does, how it starts, and whether the tests pass. If they fail before you've changed anything, that's essential to know, because otherwise you'll blame yourself later.

Check what AI tells you

AI tools are excellent at explaining unfamiliar code, and they're also confidently wrong at times. They may describe what a function's name suggests, not what the code does, or mix up two similar functions. Use them to get oriented quickly, then check the claims that matter. Open the file, or better, run the code and see.

"Unused" may not be unused

A search finds no callers, so the function looks dead. But it might be called by name from a config file, a scheduled job, a plugin system or another repository. Before you delete it, look at its history for why it was added. Then remove it in a small change of its own, and watch your logs after it ships. That way, it's easy to bring back if you were wrong. Deleting real dead code is valuable, and it's worth doing carefully.