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

# 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

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

# 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
• TypeScript: strict tsconfig, ESLint setup, discriminated unions, type safety -- see reference/typescript.md
• PHP: PHPStan config, PSR-12, enums, constructor promotion -- see reference/php.md
• Go: gofmt, error handling, receiver naming, early returns -- see reference/go.md
• Dart/Flutter: null safety, named parameters, const constructors, dart analyze -- see reference/dart.md