Skip to content

AvinashP/AgentsAtlas / skills/explaining-code

explaining-code

Verified

Explains code with diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when asked "how does this work?"

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

If they ask...Start with...
"How does X work?"High-level flow, then details
"What does this code do?"Purpose, then step-by-step
"Why is it written this way?"Problem it solves, alternatives
"I'm confused about..."Clarify specific concept

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:

Code ConceptReal-world Analogy
APIRestaurant menu + waiter
CacheSticky notes on your desk
DatabaseFiling cabinet
QueueLine at a store
StackStack of plates
Hash tableLibrary index cards
MiddlewareSecurity checkpoint
Event loopReceptionist handling calls
PromiseIOU note
ClosureBackpack carrying supplies

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
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 321kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 321kUpdated Claude CodeCodexVerifiedInstall