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
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