softspark 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