When explaining code, always include:
- Start with an analogy: Compare the code to something from everyday life
- Draw a diagram: Use ASCII art to show the flow, structure, or relationships
- Walk through the code: Explain step-by-step what happens
- Highlight a gotcha: What's a common mistake or misconception?
Keep explanations conversational. For complex concepts, use multiple analogies.
Diagram Types
Flow / Control flow:
Input -> [Validate] -> [Process] -> [Save] -> Output
|
[Error] -> Return 400Call stack / Sequence:
Client API DB
|--request--> | |
| |--query----> |
| |<--result--- |
|<-response-- | |Tree / Hierarchy:
App
+-- Header
| +-- Nav
+-- Main
| +-- Sidebar
| +-- Content
+-- FooterState machine:
[Idle] --submit--> [Loading] --success--> [Done]
|
error|
[Failed] --retry--> [Loading]Data structure:
User {
id: string
profile: Profile --> { name, avatar, bio }
posts: Post[] --> [{ id, title, body }]
}Before / After:
Before: After:
fn() fn()
doA() doA()
doB() doB()
doC() -> helpers()
doD() doC()
doE() doD()
doE()Error Handling
- Code references external files/modules -- read them before explaining
- Diagram too complex -- split into multiple focused diagrams, each covering one concept