explain-code

Explain Code

Break down complex code into clear, understandable explanations.

Usage

/explain-code [file_path] [depth]

Arguments:

• file_path - File, function, or code block to explain (required)
• depth - quick (overview), detailed (line-by-line), deep (with context)

Explanation Process

Step 1: Identify Scope

Determine what to explain:

• Single function or method
• Entire file or module
• Specific algorithm or pattern
• System interaction or flow

Step 2: Build Mental Model

Before explaining, understand:

• What problem this code solves
• Inputs and outputs
• Side effects and state changes
• Error conditions and edge cases

Step 3: Structure the Explanation

Quick Overview (default)

• One paragraph summary of purpose
• Key inputs and outputs
• Main logic flow in 3-5 bullet points

Detailed Breakdown

## Purpose
What this code accomplishes and why it exists.

## How It Works
Step-by-step walkthrough of the logic.

## Key Components
- **[Name]**: What it does
- **[Name]**: What it does

## Data Flow
Input → [transformations] → Output

## Edge Cases
- How [edge case] is handled

Deep Dive

All of the above plus:

• Why this approach was likely chosen
• Trade-offs and alternatives
• How it fits in the larger system
• Potential gotchas or maintenance notes

Step 4: Use Analogies

When explaining complex concepts:

• Find real-world analogies
• Compare to common patterns
• Use diagrams in ASCII if helpful

Request → [Middleware] → [Handler] → [Response]
              ↓              ↓
         [Logging]     [Database]

Guidelines

• Adjust technical level to context
• Start with the "why" before the "how"
• Use the code's own naming when possible
• Highlight non-obvious behavior
• Note assumptions the code makes
• Point out clever or unusual techniques