# Clean Code Walkthrough — Learn by Doing

## Before We Begin

Clean code isn't about perfection—it's about code that others (and future-you) can read, change, and debug without unnecessary friction.

**Diagnostic question:** Recall a time you struggled to understand someone else's code (or your own from months ago). What made it hard? Was it names, structure, length, or something else?

**Checkpoint:** You can name at least one concrete frustration and guess what a "clean" version might have looked like.

---

## Step 1: Improving Names

<!-- hint:code language="javascript" highlight="1,3" -->
<!-- hint:card type="concept" title="Intent-revealing names" -->

**Task:** Find a function or variable in your codebase (or use a sample) with an unclear name. Rename it to reveal intent. Before and after: what did the new name communicate that the old one didn't?

**Question:** How do you decide when a name is "good enough"? What would make you choose a longer vs shorter name?

**Checkpoint:** The user can articulate the difference between vague and intent-revealing names.

---

## Step 2: Extracting a Function

**Task:** Take a block of code that does multiple things (e.g., validates input, transforms it, and saves it). Extract one logical piece into a separate function. Ensure the extracted function has a clear, single purpose.

**Question:** How did you decide where to make the cut? What would have been a bad extraction?

**Checkpoint:** The user has a smaller, focused function and can explain the extraction boundary.

---

## Step 3: Reducing Parameters

**Task:** Find or write a function with 4+ parameters. Refactor it to accept a single object parameter. Update the call site.

**Question:** When would you keep separate parameters instead of an object? (Hint: think about 1–2 parameters with distinct roles.)

**Checkpoint:** The user understands when object parameters improve readability.

---

## Step 4: Eliminating Magic Numbers

<!-- hint:card type="warning" title="Common mistake: over-naming obvious literals" -->

**Task:** Find numeric or string literals in code that represent business concepts (status codes, limits, timeouts). Replace them with named constants. Ensure the meaning is now obvious.

**Question:** Is every literal a "magic number"? When is `0` or `1` acceptable without a constant?

**Checkpoint:** The user has replaced at least 2–3 magic values with named constants.

---

## Step 5: Simplifying Nesting

<!-- hint:buttons type="single" prompt="When nesting is deep, which approach do you prefer?" options="Early returns,Extract functions,Both depending on context" -->

**Task:** Take code with 3+ levels of nesting (if/else inside loops, etc.). Refactor using early returns or extracted functions to reduce nesting. Compare readability.

**Question:** What's the "guard clause" pattern? How does returning early simplify the rest of the function?

**Checkpoint:** The user can use early returns and reduced nesting effectively.

---

## Step 6: Comments vs Code

**Task:** Find a comment that explains *what* the code does. Delete the comment and refactor the code so it's self-explanatory. If the comment explained *why*, keep it and ensure it's accurate.

**Question:** When is a comment the right choice instead of refactoring?

**Checkpoint:** The user distinguishes good vs bad comments and prefers self-documenting code when possible.

<!-- hint:celebrate -->