Explaining Code

Explaining Code Skill

Explain code clearly using multiple techniques for different learning styles.

Workflow

1. Understand the Context

Before explaining, understand:

• What is the user's knowledge level?
• What specifically do they want to understand?
• What's the scope? (single function, module, system)

2. Choose Explanation Strategy

3. Build the Explanation

Layer your explanation:

1. One sentence summary - What is the core purpose?
2. Analogy - Relate to something familiar
3. Visual diagram - Show structure/flow
4. Walk through - Step by step with code
5. Key concepts - Highlight important patterns

4. Use Multiple Representations

Different people learn differently:

• Visual learners: Diagrams, flowcharts
• Sequential learners: Step-by-step walkthrough
• Conceptual learners: Analogies, mental models
• Hands-on learners: Example usage, experiments to try

Explanation Techniques

The Zoom Technique

Start wide, then zoom in:

System Level:  "This app handles user authentication"
     ↓
Module Level:  "This module manages sessions"
     ↓
Function Level: "This function validates tokens"
     ↓
Line Level:    "This line checks expiration"

The Analogy Technique

Connect to familiar concepts:

The Story Technique

Narrate the code as a story:

"When a user clicks login, our function wakes up.
First, it grabs the username and password from the form.
Then it sends them to the server and waits for a response.
If the server says 'OK', it saves the token and lets the user in.
If not, it shows an error message."

The Diagram Technique

Use ASCII diagrams for structure and flow:

┌─────────┐     ┌─────────┐     ┌─────────┐
│ Browser │────▶│   API   │────▶│   DB    │
└─────────┘     └─────────┘     └─────────┘
     │               │               │
     │  1. Request   │  2. Query     │
     │               │               │
     │  4. Response  │  3. Data      │
     │◀──────────────│◀──────────────│

Quick Reference

Explaining Functions

Purpose: [What problem does it solve?]
Inputs:  [What does it receive?]
Process: [What steps does it take?]
Output:  [What does it return?]
Side effects: [What else does it change?]

Example:

function calculateDiscount(price, percentage) {
  return price * (1 - percentage / 100);
}

Purpose: Calculate price after applying a percentage discount
Inputs:
  - price: The original price (e.g., 100)
  - percentage: The discount percentage (e.g., 20 for 20%)
Process:
  1. Divide percentage by 100 to get decimal (20 → 0.20)
  2. Subtract from 1 to get remaining fraction (1 - 0.20 = 0.80)
  3. Multiply by price to get discounted price (100 × 0.80 = 80)
Output: The discounted price (80)
Side effects: None

Explaining Classes

Responsibility: [What is this class in charge of?]
Data it holds:  [What state does it maintain?]
Actions it can: [What can you ask it to do?]
Collaborators:  [What other classes does it work with?]

Explaining Systems

Purpose:     [What business problem does this solve?]
Components:  [What are the major parts?]
Data flow:   [How does information move through?]
Entry points: [How do users/systems interact with it?]

Common Patterns to Explain

Callback Pattern

// "Do this task, and when you're done, call me back"
fetchData(url, function(result) {
  // This runs LATER, when data arrives
});
// Code here runs IMMEDIATELY, before data arrives

Analogy: Like ordering food and giving your number - you don't stand at the counter waiting.

Promise Pattern

// "I promise to give you a result eventually"
fetchData(url)
  .then(result => { /* handle success */ })
  .catch(error => { /* handle failure */ });

Analogy: Like a claim ticket at dry cleaning - you'll get your clothes, but not right now.

Observer Pattern

// "Tell me whenever something happens"
button.addEventListener('click', handleClick);

Analogy: Like subscribing to a newsletter - you get notified when new content arrives.

Middleware Pattern

// "Check this before passing it on"
app.use(authMiddleware);  // Runs first
app.use(loggingMiddleware); // Runs second
app.get('/api', handler);   // Runs last

Analogy: Like airport security - multiple checkpoints before you board.

See Also

• diagrams.md - ASCII diagram patterns for code visualization