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-10for 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_docswith technology:clean-codefor comprehensive documentation.
Authoritative References
| Principle | Source | Link |
|---|---|---|
| Clean Code | Robert C. Martin | Clean Code Book |
| SOLID | Robert C. Martin | SOLID Principles |
| Refactoring | Martin Fowler | Refactoring Catalog |
| Cognitive Complexity | SonarSource | Whitepaper (PDF) |
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