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