# Clean Code

> Use when the user writes new Python, or asks for review, refactor, or cleanup of Python code, names, comments/docstrings, functions, or tests. Applies Robert Martin's complete Clean Code catalog -- naming, functions, comments, DRY, boundary conditions, and tests -- to the code being changed.

- Skill: `sagargupta16/clean-code` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add sagargupta16/clean-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sagargupta16/clean-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Sagargupta16 (https://skillmd.com/u/sagargupta16)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sagargupta16/clean-code

---


# Clean Code (Python)

> "Always leave the campground cleaner than you found it."
> — Robert Baden-Powell

> "Always check a module in cleaner than when you checked it out."
> — Robert C. Martin, *Clean Code*

## Rule Chapters

Load the chapter that matches the work. Rule IDs (N1, C5, G25, F3, T9...) are defined in these files:

| Chapter | When |
|---------|------|
| [references/full-catalog.md](references/full-catalog.md) | Reviewing any Python -- the complete rule index (master) |
| [references/names.md](references/names.md) | Naming variables, functions, classes, modules |
| [references/comments.md](references/comments.md) | Writing or editing comments and docstrings |
| [references/functions.md](references/functions.md) | Creating or refactoring functions |
| [references/general.md](references/general.md) | Code quality review -- DRY, intent, abstractions |
| [references/tests.md](references/tests.md) | Writing or reviewing tests |

## The Philosophy

You don't have to make every module perfect. You simply have to make it **a little bit better** than when you found it.

If we all followed this simple rule:
- Our systems would gradually get better as they evolved
- Teams would care for the system as a whole
- The relentless deterioration of software would end

## When Working on Code

Every time you touch code, look for **at least one small improvement**:

### Quick Wins (Do These Immediately)
- Rename a poorly named variable → [references/names.md](references/names.md)
- Delete a redundant comment → [references/comments.md](references/comments.md)
- Remove dead code or unused imports
- Replace a magic number with a named constant
- Extract a deeply nested block into a well-named function

### Deeper Improvements (When Time Allows)
- Split a function that does multiple things → [references/functions.md](references/functions.md)
- Remove duplication (DRY) → [references/general.md](references/general.md)
- Add missing boundary checks
- Improve test coverage → [references/tests.md](references/tests.md)

## The Rule in Practice

```python
# You're asked to fix a bug in this function:
def proc(d, x, flag=False):
    # process data
    for i in d:
        if i > 0:
            if flag:
                x.append(i * 1.0825)  # tax
            else:
                x.append(i)
    return x

# Don't just fix the bug and leave.
# Leave it cleaner:
TAX_RATE = 0.0825

def process_positive_values(
    values: list[float],
    apply_tax: bool = False
) -> list[float]:
    """Filter positive values, optionally applying tax."""
    rate = 1 + TAX_RATE if apply_tax else 1
    return [v * rate for v in values if v > 0]
```

**What changed:**
- ✅ Descriptive function name (N1)
- ✅ Clear parameter names (N1)
- ✅ Type hints (P3)
- ✅ Named constant for magic number (G25)
- ✅ No output argument mutation (F2)
- ✅ Useful docstring (C4)

## The Mindset

**Don't:**
- Leave code worse than you found it
- Say "that's not my code"
- Wait for a dedicated refactoring sprint
- Make massive changes unrelated to your task

**Do:**
- Keep changes proportional to your task
- Improve the code you are already changing
- Leave a trail of quality improvements over time

## AI Behavior

Apply cleanup only when the task IS cleanup (review, refactor, "clean this up" asks). When writing or fixing code, follow these rules for the NEW code you write; do not expand the diff with drive-by improvements to adjacent code the user didn't ask about.

When reviewing code:
1. Load [references/full-catalog.md](references/full-catalog.md) for comprehensive rule checking
2. Flag violations by rule number
3. Suggest incremental improvements, not complete rewrites

## The Boy Scout Promise

Every piece of code you touch gets a little better. Not perfect—just better.

Over time, better compounds into excellent.