✨ Clean Code Principles
Writing code that humans can read, maintain, and extend.
Core principles
- Readability first — Code is read 10x more than it's written
- Single Responsibility — Each function/class does one thing well
- DRY — Don't Repeat Yourself, but don't abstract too early
- KISS — Keep It Simple, Stupid
- YAGNI — You Aren't Gonna Need It — don't build for hypothetical futures
Naming conventions
- Variables: describe what it holds (
userEmail, notdata) - Functions: describe what it does (
calculateTotal, notprocess) - Booleans: use prefixes (
isActive,hasPermission,canEdit) - Constants: SCREAMING_SNAKE_CASE for true constants
- Avoid abbreviations unless universally understood (
id,url,api)
Function guidelines
- Keep functions short — ideally under 20 lines
- One level of abstraction per function
- Max 3 parameters — use an object/struct beyond that
- No side effects unless clearly named (
saveUser,sendEmail) - Return early to avoid deep nesting
Code smells
| Smell | Fix |
|---|---|
| Long function | Extract smaller functions |
| Deep nesting | Return early, extract logic |
| Magic numbers | Use named constants |
| Commented-out code | Delete it (git has history) |
| God class | Split into focused classes |
| Duplicate code | Extract shared function |
Comments
- Don't comment what — the code should say that
- Comment why — explain non-obvious decisions
- TODO comments need a ticket reference
- Delete outdated comments immediately