Explain Code with AI

How It Works

Paste the code, name the language or framework, and state your level (beginner, intermediate, experienced in other languages). The explainer produces a structured breakdown that matches your level: plain language first, then technical depth only where needed, with concrete examples and clear warnings about pitfalls. All explanations use [[merge fields]] so you can adapt them for teaching or documentation.

What to Provide

Code Explanation Blueprint

This is the finished deliverable.

1. High-Level Purpose (30-Second Mental Model)

What this code does in one sentence:

[[Core job: e.g. "Takes a list of user events and returns a deduplicated, time-sorted feed grouped by day for the UI."]]

Why it exists (the problem it solves):

[[Business or technical reason: e.g. "The previous version loaded everything into memory and crashed on large accounts."]]

2. Structure Overview

Main pieces:

• [[Entry point function / component / module]]
• [[Helper functions or utilities]]
• [[Data shapes or types involved]]
• [[External dependencies or side effects]]

Control flow at a glance (numbered):

1. [[First thing that happens]]
2. [[Decision or loop]]
3. [[Side effect or return]]

3. Detailed Walkthrough (Level-Tuned)

For beginners (plain language first):

The function starts by [[doing X in simple terms]].

Then it [[checks something and decides]].

Finally it [[produces Y and returns it]].

For intermediate / review (block by block):

[[paste relevant block]]

What this block does:

• [[Line or lines]]: [[plain explanation]]
• Key detail: [[why this line or pattern exists]]

Repeat for each major block.

Variables and data shapes:

4. Key Concepts and Idioms Explained

Concept 1: [[e.g. "closure" or "useMemo" or "generator" or "context manager"]]:

[[One-paragraph explanation at your level]].

Why it is used here: [[Specific benefit in this code]].

Common gotcha: [[What beginners or reviewers miss]].

Concept 2: (repeat for 2–4 important ideas)

5. Control Flow and Data Flow

Data journey (simple diagram in words):

Raw input → [[validation or normalization]] → [[transformation or grouping]] → [[side effect or final return]].

Important branches or decisions:

• If [[condition]], then [[path A]] (e.g. early return for empty input).
• Else [[path B]].

Performance or complexity note:

• Time: [[O(n) or "linear in number of events"]]
• Space: [[O(n) for the grouped structure]]
• Hot path: [[The loop over events: keep it simple]]

6. Edge Cases and Gotchas

List the ones that matter:

1. [[Empty input or null values]] → [[what happens and why it is safe or needs handling]]
2. [[Very large input]] → [[memory or time consideration]]
3. [[Concurrent calls or re-renders]] → [[stale data risk or need for memo]]
4. [[Invalid data shape]] → [[where it would fail and how to guard]]

7. Analogy or Concrete Example (For Learning)

Simple analogy:

"Think of this function like [[a mail sorting machine in a post office: letters come in unsorted, the machine groups them by zip code (date), and hands neat bundles to the carriers (UI components)."]]

Concrete small example:

Input:
[[tiny realistic example]]

Output:
[[what you see or get]]

What the code did step by step on this input:
1. ...
2. ...

8. How to Use This Explanation

• For review: Check that the mental model matches the requirements.
• For modification: Identify the exact block to change.
• For learning: Read the concepts section, then try to explain the code back without looking.
• For docs: Copy sections 1–3 into a README or PR description and adjust.

Worked Examples

Example 1: Small Python Function (Beginner)

Code: A function that filters active users and formats names.

Level: New to Python.

Output: Plain language purpose, line-by-line, list vs generator note, edge case for empty list, simple analogy to "going through a stack of cards and pulling the ones that are still valid."

Example 2: React Component with Hooks (Intermediate)

Code: A dashboard widget that fetches data, subscribes to updates, and renders a chart.

Level: Comfortable with JS, new to React.

Output: High-level "what the component owns", useEffect + cleanup explanation, dependency array gotcha, data flow diagram, performance note about re-subscribing.

Example 3: Complex SQL Query or Backend Handler (Experienced)

Code: A query with several joins + a Python service method that processes the result.

Level: Strong engineer new to this codebase.

Output: Purpose tied to business metric, join strategy explanation, N+1 risk called out, indexing suggestion, edge case for deleted records, clean summary for PR description.

Format Checklist

Pro Tip

After reading the explanation, close it and try to explain the code to a rubber duck or in a comment. The gaps that appear are the real learning. Then re-read only those sections.

This blueprint turns opaque code into something you can reason about, review safely, and modify with intention.