Clean Code

---
name: clean-code
description: "Code quality: meaningful names, SRP, DRY, small functions, guard clauses, refactoring. Triggers: clean code, naming, code smell, SRP, DRY, long function, god class, dead code."
effort: medium
user-invocable: false
allowed-tools: Read
---

# Clean Code Skill

## Core Principles

### 1. Meaningful Names

```python
# Bad
def calc(a, b):
    return a * b

# Good
def calculate_total_price(unit_price: float, quantity: int) -> float:
    return unit_price * quantity
```

### 2. Single Responsibility

```python
# Bad - does too much
def process_user(user_data):
    validate(user_data)
    user = create_user(user_data)
    send_welcome_email(user)
    log_creation(user)
    return user

# Good - each function does one thing
def create_user(user_data: UserData) -> User:
    return User(**user_data)

def onboard_user(user_data: UserData) -> User:
    user = create_user(user_data)
    send_welcome_email(user)
    log_user_creation(user)
    return user
```

### 3. DRY (Don't Repeat Yourself)

```python
# Bad
def get_active_users():
    return [u for u in users if u.status == "active"]

def get_active_admins():
    return [u for u in users if u.status == "active" and u.role == "admin"]

# Good
def filter_users(status: str | None = None, role: str | None = None) -> list[User]:
    result = users
    if status:
        result = [u for u in result if u.status == status]
    if role:
        result = [u for u in result if u.role == role]
    return result
```

---

## Code Organization

Keep modules focused. Order contents consistently: imports (stdlib, third-party, local), constants, public API, private helpers. Use clear visibility markers (underscore prefix in Python, access modifiers in other languages). Group related functionality into cohesive modules rather than dumping everything into a single file.

---

## Anti-Patterns to Avoid

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| God class | Too many responsibilities | Split into smaller classes |
| Long methods | Hard to understand | Extract methods |
| Deep nesting | Complex control flow | Early returns, extract methods |
| Magic numbers | Unclear meaning | Use named constants |
| Bare except | Hides bugs | Catch specific exceptions |
| Mutable defaults | Shared state bugs | Use `None` and create inside |

---

## Quality Checklist

- [ ] Functions are small (<20 lines ideal)
- [ ] Names are descriptive and consistent
- [ ] Type hints on all public APIs
- [ ] Docstrings on all public functions/classes
- [ ] No magic numbers (use constants)
- [ ] No hardcoded strings (use enums/constants)
- [ ] Error handling is specific
- [ ] Resources are properly cleaned up
- [ ] No code duplication
- [ ] Tests cover critical paths
- [ ] **No dead code** — grep-verified zero references for every removed/renamed symbol; pre-existing dead code touched by this change is deleted too (Constitution Art. VI.1)
- [ ] **Every found bug fixed** — bugs, missing tests for changed behavior, and stale docs discovered during the task are fixed in the same change, not deferred (Constitution Art. VI.2)

---

## Common Rationalizations

| Excuse | Why It's Wrong |
|--------|----------------|
| "It's readable enough" | "Enough" means someone will misread it eventually — clarity prevents incidents |
| "Refactoring for readability is gold-plating" | Readability is maintainability — future you will thank present you |
| "Short variable names are faster to type" | You type it once, readers parse it hundreds of times — optimize for reading |
| "DRY means never repeat anything" | Wrong DRY creates coupling — duplicate until you see the real abstraction |
| "More abstractions = cleaner code" | Premature abstraction is worse than duplication — wait for the third use |
| "That dead file is pre-existing, not my problem" | If your change makes it verifiably unused, deleting it IS your problem (Constitution Art. VI.1) |
| "I'll fix the missing test in a separate PR" | Forbidden when the test covers behavior you just changed — add it now (Constitution Art. VI.2) |
| "Świadome pominięcie" / "out of scope" | Deferral of directly-adjacent fixes is forbidden; if a user decision is needed, ASK, don't bury it |

## Language-Specific References

For detailed patterns, type hints, linting configuration, and idiomatic code per language:

- **Python:** type hints, docstrings, error handling, context managers, module/class structure, ruff/mypy config -- see [reference/python.md](reference/python.md)
- **TypeScript:** strict tsconfig, ESLint setup, discriminated unions, type safety -- see [reference/typescript.md](reference/typescript.md)
- **PHP:** PHPStan config, PSR-12, enums, constructor promotion -- see [reference/php.md](reference/php.md)
- **Go:** gofmt, error handling, receiver naming, early returns -- see [reference/go.md](reference/go.md)
- **Dart/Flutter:** null safety, named parameters, const constructors, dart analyze -- see [reference/dart.md](reference/dart.md)