---
name: Clean Code
slug: clean-code-4
category: Quality
description: Clean Code helps you improve readability and maintainability by applying meaningful names, SRP, DRY, small functions, and guard clauses. Use it when reviewing or refactoring code with smells like long methods, god classes, or dead code.
github: "https://github.com/softspark/ai-toolkit/tree/main/app/skills/clean-code"
language: Python
stars: 170
forks: 20
install: "npx degit https://github.com/softspark/ai-toolkit/tree/main/app/skills/clean-code ~/.claude/skills/clean-code"
installs_to: ~/.claude/skills/clean-code
source_path: app/skills/clean-code/SKILL.md
collection_size: 25
category_size: 1897
collection_url: "https://dirskills.com/collections/softspark/ai-toolkit"
added: 2026-09-08T05:33:49.374Z
last_synced: 2026-09-08T05:33:49.374Z
canonical_url: "https://dirskills.com/skills/clean-code-4"
---

# Clean Code

Clean Code helps you improve readability and maintainability by applying meaningful names, SRP, DRY, small functions, and guard clauses. Use it when reviewing or refactoring code with smells like long methods, god classes, or dead code.

**Install:**

```bash
npx degit https://github.com/softspark/ai-toolkit/tree/main/app/skills/clean-code ~/.claude/skills/clean-code
```

## README

# 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)