code-explainer

Code Explainer

Iron Law

TWO LEVELS EVERY TIME — NEVER COLLAPSE THEM INTO ONE

Level 1 is for someone who uses the code. Level 2 is for someone who changes it. They need different information. Mixing them makes both audiences worse off.

When to Use

• Inheriting code you did not write
• Onboarding a new developer to an existing module
• Preparing to modify something you haven't touched in months
• Handing off ownership to another team
• Writing documentation from code

The Four Outputs (All Mandatory)

Level 1 — For the User (what it does)

Explain what this code accomplishes in plain language. No jargon. A non-technical stakeholder should be able to read this and understand:

• What problem the code solves
• What inputs it needs
• What it produces or causes to happen

Write this as if you're explaining to a product manager, not a developer.

Level 2 — For the Modifier (why it is built this way)

Explain the architectural decisions. A senior engineer about to touch this code needs to know:

• Why is it structured this way? (not just what it does)
• What would break if you changed X?
• What are the dependencies — internal and external?
• Where are the edge cases? What inputs cause unexpected behavior?
• What assumptions are baked in that aren't obvious from reading?
• What would a senior engineer want to verify before touching this?

Do not dumb this down. Level 2 readers are technical.

The Fragile Part (1 sentence, mandatory)

The section of this code most likely to break under unexpected conditions — unusual inputs, concurrent access, external failures, edge-case data. Name the specific location (function, line, block), not a general area.

The Assumption (1 sentence, mandatory)

The key assumption baked into this code that, if wrong, causes it to fail. This is not an edge case — it's a design premise. Examples: "assumes the caller always passes a non-null user object", "assumes the upstream API returns items in chronological order", "assumes this runs in a single-threaded context".