clean-code-principles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean Code Principles

整洁代码原则

Fundamental software design principles, SOLID, design patterns, and clean code practices. Language-agnostic guidelines for writing maintainable, scalable software.

基础软件设计原则、SOLID、设计模式及整洁代码实践。与语言无关的可维护、可扩展软件编写指南。

When to Apply

适用场景

Reference these guidelines when:

Designing new features or systems
Reviewing code architecture
Refactoring existing code
Discussing design decisions
Improving code quality

以下场景可参考这些指南：

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

Rule Categories by Priority

按优先级划分的规则类别


solid-
core-
pattern-
org-
name-
func-
doc-

Priority	Category	Impact	Prefix
1	SOLID Principles	CRITICAL	`solid-`
2	Core Principles	CRITICAL	`core-`
3	Design Patterns	HIGH	`pattern-`
4	Code Organization	HIGH	`org-`
5	Naming & Readability	MEDIUM	`name-`
6	Functions & Methods	MEDIUM	`func-`
7	Comments & Documentation	LOW	`doc-`


solid-
core-
pattern-
org-
name-
func-
doc-

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

Quick Reference

快速参考

1. SOLID Principles (CRITICAL)

1. SOLID原则（关键）

```
solid-srp
```
- Single Responsibility Principle
```
solid-ocp
```
- Open/Closed Principle
```
solid-lsp
```
- Liskov Substitution Principle
```
solid-isp
```
- Interface Segregation Principle
```
solid-dip
```
- Dependency Inversion Principle

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

2. Core Principles (CRITICAL)

2. 核心原则（关键）

```
core-dry
```
- Don't Repeat Yourself
```
core-kiss
```
- Keep It Simple, Stupid
```
core-yagni
```
- You Aren't Gonna Need It
```
core-separation-of-concerns
```
- Separate different responsibilities
```
core-composition-over-inheritance
```
- Favor composition
```
core-law-of-demeter
```
- Principle of least knowledge
```
core-fail-fast
```
- Detect and report errors early
```
core-encapsulation
```
- Hide implementation details

```
core-dry
```
- 避免重复（Don't Repeat Yourself）
```
core-kiss
```
- 保持简单（Keep It Simple, Stupid）
```
core-yagni
```
- 无需过度设计（You Aren't Gonna Need It）
```
core-separation-of-concerns
```
- 关注点分离
```
core-composition-over-inheritance
```
- 优先使用组合
```
core-law-of-demeter
```
- 迪米特法则（最少知识原则）
```
core-fail-fast
```
- 快速失败
```
core-encapsulation
```
- 封装

3. Design Patterns (HIGH)

3. 设计模式（高）

```
pattern-factory
```
- Factory pattern for object creation
```
pattern-strategy
```
- Strategy pattern for algorithms
```
pattern-repository
```
- Repository pattern for data access
```
pattern-decorator
```
- Decorator pattern for behavior extension
```
pattern-observer
```
- Observer pattern for event handling
```
pattern-adapter
```
- Adapter pattern for interface conversion
```
pattern-facade
```
- Facade pattern for simplified interfaces
```
pattern-dependency-injection
```
- DI for loose coupling

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

4. Code Organization (HIGH)

4. 代码组织（高）

```
org-feature-folders
```
- Organize by feature, not layer
```
org-module-boundaries
```
- Clear module boundaries
```
org-layered-architecture
```
- Proper layer separation
```
org-package-cohesion
```
- Related code together
```
org-circular-dependencies
```
- Avoid circular imports

```
org-feature-folders
```
- 按功能而非分层组织代码
```
org-module-boundaries
```
- 清晰的模块边界
```
org-layered-architecture
```
- 合理的分层架构
```
org-package-cohesion
```
- 相关代码聚合
```
org-circular-dependencies
```
- 避免循环依赖

5. Naming & Readability (MEDIUM)

5. 命名与可读性（中）

```
name-meaningful
```
- Use intention-revealing names
```
name-consistent
```
- Consistent naming conventions
```
name-searchable
```
- Avoid magic numbers/strings
```
name-avoid-encodings
```
- No Hungarian notation
```
name-domain-language
```
- Use domain terminology

```
name-meaningful
```
- 使用表意明确的命名
```
name-consistent
```
- 保持命名一致性
```
name-searchable
```
- 避免魔法数字/字符串
```
name-avoid-encodings
```
- 不使用匈牙利命名法
```
name-domain-language
```
- 使用领域术语

6. Functions & Methods (MEDIUM)

6. 函数与方法（中）

```
func-small
```
- Keep functions small
```
func-single-purpose
```
- Do one thing
```
func-few-arguments
```
- Limit parameters
```
func-no-side-effects
```
- Minimize side effects
```
func-command-query
```
- Separate commands and queries

```
func-small
```
- 保持函数精简
```
func-single-purpose
```
- 单一职责
```
func-few-arguments
```
- 限制参数数量
```
func-no-side-effects
```
- 最小化副作用
```
func-command-query
```
- 分离命令与查询

7. Comments & Documentation (LOW)

7. 注释与文档（低）

```
doc-self-documenting
```
- Code should explain itself
```
doc-why-not-what
```
- Explain why, not what
```
doc-avoid-noise
```
- No redundant comments
```
doc-api-docs
```
- Document public APIs

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

Essential Guidelines

核心指南

For detailed examples and explanations, see the rule files:

core-dry.md - Don't Repeat Yourself principle
pattern-repository.md - Repository pattern for data access

如需详细示例与解释，请查看规则文件：

core-dry.md - 避免重复原则
pattern-repository.md - 数据访问仓库模式

SOLID Principles (Summary)

SOLID原则（摘要）

Principle	Definition
Single Responsibility	A class should have only one reason to change
Open/Closed	Open for extension, closed for modification
Liskov Substitution	Subtypes must be substitutable for base types
Interface Segregation	Don't force clients to depend on unused interfaces
Dependency Inversion	Depend on abstractions, not concretions

原则	定义
Single Responsibility	一个类应该只有一个引起变化的原因
Open/Closed	对扩展开放，对修改关闭
Liskov Substitution	子类必须能够替换其基类
Interface Segregation	不要强迫客户端依赖未使用的接口
Dependency Inversion	依赖抽象而非具体实现

Core Principles (Summary)

核心原则（摘要）

Principle	Definition
DRY	Don't Repeat Yourself - single source of truth
KISS	Keep It Simple - avoid over-engineering
YAGNI	You Aren't Gonna Need It - build only what's needed

原则	定义
DRY	避免重复 - 单一事实来源
KISS	保持简单 - 避免过度设计
YAGNI	无需过度设计 - 只构建当前需要的功能

Quick Examples

快速示例

typescript

// 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) { }

typescript

// 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) { }

Output Format

输出格式

When auditing code, output findings in this format:

file:line - [principle] Description of issue

Example:

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

代码审计时，请按以下格式输出结果：

file:line - [principle] 问题描述

示例：

src/services/UserService.ts:15 - [solid-srp] 该类同时处理验证、持久化和通知逻辑
src/utils/helpers.ts:42 - [core-dry] 邮箱验证逻辑与validators/email.ts中重复
src/models/Order.ts:28 - [name-meaningful] 变量'x'应明确其用途

How to Use

使用方法

Read individual rule files for detailed explanations:

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

查看单个规则文件获取详细说明：

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

References

参考资料

This skill is built on established software engineering principles:

本技能基于成熟的软件工程原则构建：

Core Books

核心书籍

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 wisdom

Clean Code by Robert C. Martin - 整洁代码实践的基石
Design Patterns by Gang of Four - 经典设计模式目录
Refactoring by Martin Fowler - 代码结构优化指南
The Pragmatic Programmer by Hunt & Thomas - 实用编程智慧

Online Resources

在线资源

Refactoring Guru - Design patterns and code smells
Martin Fowler's Refactoring Catalog - Comprehensive refactoring techniques
Uncle Bob's Clean Coder Blog - Software craftsmanship articles

Refactoring Guru - 设计模式与代码坏味道
Martin Fowler's Refactoring Catalog - 全面的重构技术
Uncle Bob's Clean Coder Blog - 软件工艺相关文章

Pattern Catalogs

模式目录

Metadata

元数据

Version: 1.0.0 Status: Active Coverage: 23 rules across 3 categories (SOLID, Core Principles, Design Patterns) Last Updated: 2026-01-17

版本： 1.0.0 状态： 活跃 覆盖范围： 3个类别（SOLID、核心原则、设计模式）共23条规则 最后更新： 2026-01-17

Rule Statistics

规则统计

SOLID Principles: 10 rules
Core Principles: 12 rules
Design Patterns: 1 rule

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

License

许可证

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

MIT License

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人，不受限制地处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，以及允许向其提供软件的人做出上述行为，但须符合以下条件：

本软件按“原样”提供，不提供任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权担保。在任何情况下，作者或版权持有人均不对因软件或软件的使用或其他交易而产生的任何索赔、损害或其他责任承担责任，无论是在合同诉讼、侵权诉讼或其他诉讼中。