Enforces clean code principles including naming, function design, comment discipline, and code organization for readable and maintainable software at any scale.
## Clean Code Rules
### Naming
- Names must reveal intent — a reader should understand purpose without reading implementation
- Variable names: nouns or noun phrases that describe what they hold (`userEmail`, not `e` or `x`)
- Function names: verbs or verb phrases describing what they do (`getUserById`, not `user`)
- Boolean variables and functions: use `is`, `has`, `can`, `should` prefixes (`isActive`, `hasPermission`)
- Avoid mental mapping: `i`, `j` are acceptable in tight loops; everywhere else use domain names
- Avoid disinformation: `accountList` must be a list; if it is a map, name it `accountMap`
- Do not encode type information in names: `userString`, `nameStr` — type systems handle that
- Replace magic numbers with named constants: `const MAX_RETRY_COUNT = 3`, not `if (retries > 3)`
### Functions
- Functions must do one thing — if a function does "A and B", split it
- Functions should be short: under 20 lines is a good target; under 10 is better
- Function arguments: 0 is ideal, 1 is good, 2 is acceptable, 3 needs justification, 4+ is a code smell
- Arguments with the same type and adjacent position are dangerous — use named parameters or objects
- Functions must operate at a single level of abstraction — do not mix high-level logic with low-level detail
- Functions must not have side effects beyond their stated purpose
- Functions that return `void` must indicate side effects in their name: `saveToDatabase`, not `process`
- Avoid flag arguments (`doSomething(true, false)`) — they indicate a function doing multiple things
### Comments
- The best comment is a well-named function or variable — prefer renaming over commenting
- Write comments to explain WHY, not WHAT — the code itself shows what it does
- Legal comments (copyright, license) are acceptable; TODO comments must include a ticket reference
- Delete commented-out code — version control history preserves old code
- Do not write redundant comments: `// increment counter` above `count++` adds no value
- Avoid misleading comments — outdated comments are worse than no comments
### Code Organization
- Keep related code close together — the "newspaper metaphor": high-level at top, details at bottom
- Instance variables at the top of a class; public methods before private helpers
- Caller functions should appear above the functions they call (top-down readability)
- One class per file; one concept per class; no mixed abstraction levels in the same file
- Group imports by source: standard library, third-party, internal — in that order
### Error Handling
- Use exceptions instead of error codes — exceptions separate the happy path from error handling
- Never return `null` — return an empty collection, `Optional`, or throw a specific exception
- Never pass `null` as a function argument — design APIs that do not require null parameters
- Write error messages that answer: what went wrong, where it happened, and what context was involved
- Catch specific exception types — never catch `Exception` (or `Throwable`) unless rethrowing
### Classes
- Classes should be small — measured by responsibilities, not lines
- Class names are nouns: `UserService`, `OrderRepository`, `InvoiceCalculator`
- Instance variables should be private; expose via methods, not direct access
- Encapsulate what varies — hide implementation details behind stable interfaces
- A class that needs to know too much about another class is a coupling smell — extract or invert the dependency
### DRY & Duplication
- Every piece of knowledge must have a single, authoritative representation in the system
- Duplication is the root of evil — two copies of the same logic diverge and cause bugs
- Do not copy-paste code between files — extract to a shared function or module
- Template method and strategy patterns eliminate algorithmic duplication
### Formatting
- Code must be formatted consistently — use a formatter (Prettier, gofmt, rustfmt, Black) on every save
- Horizontal alignment of multiple lines is an anti-pattern — it creates meaningless visual structure
- Blank lines separate concepts; related lines are grouped without blank lines between them
### Anti-patterns
- Deeply nested code (3+ levels of `if`/`for`) — flatten with early returns and extracted functions
- Long parameter lists — wrap related parameters in an object
- Divergent change: one class changed for multiple reasons — violates SRP
- Shotgun surgery: one change requires editing many classes — coupling problem
Mindaxis