clean-code-principles

Clean Code 原则

基础软件设计原则、SOLID、设计模式和整洁代码实践。适用于各种编程语言的指南，助你编写易于维护、可扩展的软件。

适用场景

在以下情况下参考这些指南：

• 设计新功能或系统
• 审查代码架构
• 重构现有代码
• 讨论设计决策
• 提升代码质量

按优先级划分的规则类别

优先级	类别	影响	前缀
1	SOLID 原则	严重	solid-
2	核心原则	严重	core-
3	设计模式	高	pattern-
4	代码组织	高	org-
5	命名与可读性	中	name-
6	函数与方法	中	func-
7	注释与文档	低	doc-

快速参考

1. SOLID 原则（严重）

• solid-srp - 单一职责原则
• solid-ocp - 开闭原则
• solid-lsp - 里氏替换原则
• solid-isp - 接口隔离原则
• solid-dip - 依赖反转原则

2. 核心原则（严重）

• core-dry - 不要重复自己
• core-kiss - 保持简单
• core-yagni - 你不会需要它
• core-separation-of-concerns - 分离不同职责
• core-composition-over-inheritance - 优先使用组合
• core-law-of-demeter - 最少知识原则
• core-fail-fast - 尽早检测并报告错误
• core-encapsulation - 隐藏实现细节

3. 设计模式（高）

• pattern-factory - 使用工厂模式创建对象
• pattern-strategy - 使用策略模式实现算法
• pattern-repository - 使用仓储模式访问数据
• pattern-decorator - 使用装饰器模式扩展行为
• pattern-observer - 使用观察者模式处理事件
• pattern-adapter - 使用适配器模式转换接口
• pattern-facade - 使用外观模式简化接口
• pattern-dependency-injection - 使用 DI 实现松耦合

4. 代码组织（高）— 计划中

• org-feature-folders - 按功能而非层组织
• org-module-boundaries - 明确模块边界
• org-layered-architecture - 正确分离各层
• org-package-cohesion - 将相关代码放在一起
• org-circular-dependencies - 避免循环导入

5. 命名与可读性（中）— 计划中

• name-meaningful - 使用能体现意图的名称
• name-consistent - 保持命名约定一致
• name-searchable - 避免魔法数字和字符串
• name-avoid-encodings - 不使用匈牙利命名法
• name-domain-language - 使用领域术语

6. 函数与方法（中）— 计划中

• func-small - 保持函数简短
• func-single-purpose - 每个函数只做一件事
• func-few-arguments - 限制参数数量
• func-no-side-effects - 尽量减少副作用
• func-command-query - 分离命令与查询

7. 注释与文档（低）— 计划中

• doc-self-documenting - 代码应能自我说明
• doc-why-not-what - 解释原因，而非内容
• doc-avoid-noise - 避免冗余注释
• doc-api-docs - 为公共 API 编写文档

核心指南

如需详细示例和说明，请参阅规则文件：

• core-dry.md - 不要重复自己原则
• pattern-repository.md - 使用仓储模式访问数据

SOLID 原则（摘要）

原则	定义
Single Responsibility	一个类应只有一个需要修改的理由
Open/Closed	对扩展开放，对修改关闭
Liskov Substitution	子类型必须可替代基类型
Interface Segregation	不要强迫客户端依赖未使用的接口
Dependency Inversion	依赖抽象，而非具体实现

核心原则（摘要）

原则	定义
DRY	不要重复自己（Don't Repeat Yourself）——单一事实来源
KISS	保持简单（Keep It Simple）——避免过度设计
YAGNI	你不会需要它（You Aren't Gonna Need It）——只构建所需内容

快速示例

// Single Responsibility - one class, one job
class UserService {
  constructor(
    private validator: UserValidator,
    private repository: UserRepository,
  ) {}

  createUser(data) {
    this.validator.validate(data);
    return this.repository.create(data);
  }
}

// Dependency Inversion - depend on abstractions
interface Repository<T> {
  find(id: string): Promise<T | null>;
  save(entity: T): Promise<T>;
}

class OrderService {
  constructor(private repository: Repository<Order>) {}
}

// DRY - single source of truth
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
const isValidEmail = (email: string) => EMAIL_REGEX.test(email);

// Meaningful names over magic numbers
const MINIMUM_AGE = 18;
if (user.age >= MINIMUM_AGE) { }

输出格式

审查代码时，请按以下格式输出发现的问题：

file:line - [principle] Description of issue

示例：

src/services/UserService.ts:15 - [solid-srp] Class handles validation, persistence, and notifications
src/utils/helpers.ts:42 - [core-dry] Email validation duplicated from validators/email.ts
src/models/Order.ts:28 - [name-meaningful] Variable 'x' should describe its purpose

使用方法

阅读各条规则文件，了解详细说明：

rules/solid-srp-class.md
rules/core-dry.md
rules/pattern-repository.md

参考资料

此技能基于成熟的软件工程原则：

核心书籍

• Clean Code，Robert C. Martin 著——整洁代码实践的基础
• Design Patterns，Gang of Four 著——经典设计模式目录
• Refactoring，Martin Fowler 著——改进代码结构
• The Pragmatic Programmer，Hunt 和 Thomas 著——实用智慧

在线资源

• Refactoring Guru——设计模式和代码异味
• Martin Fowler's Refactoring Catalog——全面的重构技巧
• Uncle Bob's Clean Coder Blog——软件工艺文章

模式目录

• Refactoring Guru - Design Patterns
• Martin Fowler - Enterprise Patterns

元数据

版本： 1.0.2 状态： 活跃 覆盖范围： 3 个已实现类别（SOLID、核心原则、设计模式）中的 23 条规则；另有 4 条计划中 最后更新： 2026-03-07

规则统计

• SOLID 原则：10 条规则
• 核心原则：12 条规则
• 设计模式：1 条规则