Universal Code Quality Principles
When NOT to Use This Skill
- Language-specific rules - Use TypeScript/Java/Python skills for syntax/idioms
- Security issues - Use
owasp-top-10 for vulnerabilities - Testing strategies - Use Vitest/Playwright skills for test quality
- Linting configuration - Use ESLint/Biome skills for tool setup
Deep Knowledge: Use mcp__documentation__fetch_docs with technology: clean-code for comprehensive documentation.
Authoritative References
Clean Code Principles
Naming
- Intention-revealing: Names should explain purpose
- Pronounceable: Avoid abbreviations
- Searchable: Avoid single letters except loops
Functions
- Small: 20 lines max, ideally < 10
- Single purpose: Do one thing well
- Few arguments: 0-2 ideal, 3 max
Comments
- Code should be self-documenting
- Comments explain "why", not "what"
- Avoid redundant comments
SOLID Principles
| Principle | Description | Violation Sign |
|---|
| Single Responsibility | One reason to change | Class does too much |
| Open/Closed | Open for extension, closed for modification | Switch statements on type |
| Liskov Substitution | Subtypes must be substitutable | Override throws exception |
| Interface Segregation | Many specific interfaces | Unused interface methods |
| Dependency Inversion | Depend on abstractions | new in business logic |
Code Metrics & Thresholds
Complexity Metrics
| Metric | Description | Threshold | Tool |
|---|
| Cyclomatic Complexity | Number of independent paths | < 10 | SonarQube, ESLint |
| Cognitive Complexity | How hard to understand | < 15 | SonarQube |
| Lines per Function | Function length | < 30 | All linters |
| Parameters | Function arguments | < 4 | All linters |
| Nesting Depth | If/loop nesting | < 4 | SonarQube |
Quality Gates (SonarQube Standard)
| Metric | Condition | Target |
|---|
| Coverage | on new code | > 80% |
| Duplications | on new code | < 3% |
| Maintainability Rating | overall | A |
| Reliability Rating | overall | A |
| Security Rating | overall | A |
Code Smells Categories
Bloaters
- Long Method
- Large Class
- Long Parameter List
- Data Clumps
Object-Orientation Abusers
- Switch Statements
- Refused Bequest
- Alternative Classes with Different Interfaces
Change Preventers
- Divergent Change
- Shotgun Surgery
- Parallel Inheritance Hierarchies
Dispensables
- Dead Code
- Duplicate Code
- Lazy Class
- Speculative Generality
Couplers
- Feature Envy
- Inappropriate Intimacy
- Message Chains
Refactoring Patterns
| Smell | Refactoring | Description |
|---|
| Long Method | Extract Method | Break into smaller functions |
| Duplicate Code | Extract Method/Class | Create reusable unit |
| Long Parameter List | Introduce Parameter Object | Group related params |
| Switch on Type | Replace with Polymorphism | Use strategy pattern |
| Feature Envy | Move Method | Put behavior with data |
| God Class | Extract Class | Split responsibilities |
Full Catalog: https://refactoring.com/catalog/
Quick Checklist
## Code Review Checklist
### Readability
- [ ] Clear, intention-revealing names
- [ ] Functions are small and focused
- [ ] No magic numbers/strings
- [ ] Appropriate abstraction level
### Maintainability
- [ ] Single Responsibility followed
- [ ] No code duplication (DRY)
- [ ] Dependencies injected, not created
- [ ] Easy to test in isolation
### Reliability
- [ ] Edge cases handled
- [ ] Errors handled appropriately
- [ ] No null pointer risks
- [ ] Resources properly closed
### Performance
- [ ] No N+1 queries
- [ ] Appropriate data structures
- [ ] No premature optimization
- [ ] Caching where appropriate
Anti-Patterns
| Anti-Pattern | Why It's Bad | Correct Approach |
|---|
| God Class (1000+ lines) | Violates SRP, hard to test | Split into focused classes |
| Magic numbers everywhere | Unclear meaning, hard to change | Use named constants |
| Deep nesting (5+ levels) | Hard to understand | Extract methods, early returns |
| Long parameter lists (6+ params) | Hard to remember order | Use parameter objects/builders |
| Copy-paste programming | Duplication, maintenance nightmare | Extract shared logic to functions |
| No error handling | Silent failures | Explicit error handling with logging |
Quick Troubleshooting
| Issue | Likely Cause | Solution |
|---|
| Function has complexity > 20 | Too many branches/loops | Extract sub-functions, use strategy pattern |
| Class over 500 lines | Multiple responsibilities | Apply SRP, split into multiple classes |
| Tests hard to write | Tight coupling, no DI | Use dependency injection |
| Same code in 3+ places | No abstraction | Extract to shared function/class |
| Function takes 10+ parameters | Poor abstraction | Create parameter object or builder |
| Code hard to understand | Poor naming, no abstraction | Refactor with intention-revealing names |
Related Skills
- Language-specific rules:
languages/typescript, languages/java, languages/python - Security:
security/owasp-top-10 - Design Patterns:
best-practices/design-patterns
