Clean Code Principles
Fundamental software design principles for writing maintainable, scalable code.
Version: 1.0.2 Rules: 23 (10 SOLID + 12 Core + 1 Pattern); 4 categories planned License: MIT
Overview
Language-agnostic guidelines covering SOLID principles, core coding principles (DRY, KISS, YAGNI), and design patterns. Examples are written in TypeScript but apply to any object-oriented or functional language.
Categories (23 rules implemented)
1. SOLID Principles (Critical) — 10 rules
Five fundamental object-oriented design principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.
2. Core Principles (Critical) — 12 rules
DRY (3 rules), KISS (2 rules), YAGNI (2 rules), Separation of Concerns, Composition over Inheritance, Law of Demeter, Fail Fast, Encapsulation.
3. Design Patterns (High) — 1 rule
Repository pattern for data access abstraction.
4. Code Organization (High) — planned
Feature folders, module boundaries, layered architecture, package cohesion, circular dependency prevention.
5. Naming & Readability (Medium) — planned
Meaningful names, consistent conventions, no magic numbers, domain language.
6. Functions & Methods (Medium) — planned
Small functions, single purpose, limited parameters, pure functions, command-query separation.
7. Comments & Documentation (Low) — planned
Self-documenting code, explain why not what, avoid noise, document public APIs.
Usage
Ask Claude to:
- "Review architecture" — triggers SOLID + Separation of Concerns analysis
- "Check SOLID principles" — targeted SOLID review
- "Check code quality" — DRY, KISS, YAGNI audit
- "Suggest design patterns" — pattern recommendations
- "Refactoring advice" — actionable improvements with rule references
Key Principles
SOLID
| Principle | Rule | Summary |
|---|---|---|
| Single Responsibility | solid-srp-class, solid-srp-function |
One reason to change |
| Open/Closed | solid-ocp-extension, solid-ocp-abstraction |
Open for extension, closed for modification |
| Liskov Substitution | solid-lsp-contracts, solid-lsp-preconditions |
Subtypes must be substitutable |
| Interface Segregation | solid-isp-clients, solid-isp-interfaces |
Small, focused interfaces |
| Dependency Inversion | solid-dip-abstractions, solid-dip-injection |
Depend on abstractions |
Core
| Principle | Rules | Summary |
|---|---|---|
| DRY | core-dry, core-dry-extraction, core-dry-single-source |
Single source of truth |
| KISS | core-kiss-simplicity, core-kiss-readability |
Simplest solution that works |
| YAGNI | core-yagni-features, core-yagni-abstractions |
Build only what's needed |
Output Format
When auditing code:
file:line - [rule-id] Description of issue
Example:
src/services/UserService.ts:15 - [solid-srp-class] Class handles validation, persistence, and email
src/utils/helpers.ts:42 - [core-dry] Email validation duplicated from validators/email.ts
src/models/Order.ts:28 - [core-yagni-abstractions] Generic abstraction used in only one place
References
- Clean Code by Robert C. Martin — Foundation for clean code practices
- Design Patterns by Gang of Four — Classic design pattern catalog
- Refactoring by Martin Fowler — Improving code structure
- The Pragmatic Programmer by Hunt & Thomas — Practical software wisdom
- Refactoring Guru — Design patterns and code smells
- Martin Fowler's Refactoring Catalog — Comprehensive techniques