shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

quality-common

Universal code quality principles applicable to all languages. Covers Clean Code, SOLID, complexity metrics, and quality standards. USE WHEN: user mentions "clean code", "SOLID", "code smells", "refactoring", "complexity", asks about "cyclomatic complexity", "cognitive complexity", "code review", "maintainability" DO NOT USE FOR: language-specific linting - use ESLint/Biome skills, security - use OWASP skills, testing - use testing skills

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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