Lesson 9 / 25

Explaining Unfamiliar Code

Use an assistant as a reading companion for code you did not write.

Ask for layers of explanation

When you join a new codebase, ask the assistant for a map first ("what are the main modules and how do they connect?"), then drill into one file, then one function, then one tricky line. Ask it to explain why, not only what, and to give an example input and output. Then verify the claims against the code, because a confident explanation can still be wrong.

Understand, build, fix, improve

Four tasks cover most daily use: explaining code, writing it, debugging it and refactoring it.

Four tasks: explain, write, debug, refactor.
Figure 3.1 — Explain, write, debug and refactor.

A prompt for reading code

Asking for a worked example makes the explanation concrete and easy to check by running it.

Explain this function for a new team member.
1. One sentence: what it does.
2. Walk through it line by line, noting any non-obvious parts.
3. Show a sample input and the exact output.
4. List edge cases where it could fail.

<paste the function>

Run it to confirm

If the explanation says "returns the last three items", run the function on a sample and see. Turning claims into small experiments is the fastest way to learn and to catch wrong explanations.

Quick check: How should you treat an assistant's explanation of code?

  • As useless
  • As always correct
  • As a helpful hypothesis to verify against the code
  • As a legal document
Answer

As a helpful hypothesis to verify against the code — Explanations speed up understanding, but you confirm them by reading or running the code.