89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# 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 |
|
|
|-----------|------|---------|
|
|
| **S**ingle Responsibility | `solid-srp-class`, `solid-srp-function` | One reason to change |
|
|
| **O**pen/Closed | `solid-ocp-extension`, `solid-ocp-abstraction` | Open for extension, closed for modification |
|
|
| **L**iskov Substitution | `solid-lsp-contracts`, `solid-lsp-preconditions` | Subtypes must be substitutable |
|
|
| **I**nterface Segregation | `solid-isp-clients`, `solid-isp-interfaces` | Small, focused interfaces |
|
|
| **D**ependency 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](https://refactoring.guru/) — Design patterns and code smells
|
|
- [Martin Fowler's Refactoring Catalog](https://refactoring.com/catalog/) — Comprehensive techniques
|