# 面向 AI 代码生成的整洁代码规则

这些规则用于指导代码生成，帮助产出可维护、专业水准的代码。

## 有意义的命名
- 使用能体现意图的名称，说明它为什么存在
- 避免误导性命名和无意义区分，例如 `data`、`info`、`manager`
- 使用可读、可搜索的名称
- 类名使用名词，例如 `UserAccount`、`PaymentProcessor`
- 方法名使用动词，例如 `calculateTotal`、`sendEmail`
- 避免脑内映射和编码风格命名，例如匈牙利命名法、前缀

## 函数
- 保持函数短小精炼，理想情况下少于 20 行
- 只做一件事，遵循单一职责原则
- 每个函数只处理一个抽象层级
- 限制参数数量，理想为 0-2 个，最多 3 个，避免布尔标志参数
- 不要产生副作用，函数应该做它名字所说的事
- 将命令与查询分离，命令修改状态，查询返回信息
- 优先使用异常而不是错误码

## 注释
- 代码本身应该尽量可自解释，能不写注释就不写
- 好的注释包括：法律信息、警告、TODO、公共 API 文档
- 坏的注释包括：重复、误导，或者只是解释糟糕的代码
- 不要注释掉代码，直接删除，版本控制会保留历史
- 如果你需要写注释，先考虑重构代码

## 格式化
- 保持文件小而聚焦
- 垂直格式化：相关概念放近一些，空行分隔不同概念
- 水平格式化：限制行长度在 80-120 个字符之间
- 使用一致的缩进和团队风格
- 将相关函数分组放在一起

## 对象与数据结构
- 对象：通过抽象隐藏数据，通过方法暴露行为
- 数据结构：暴露数据，尽量少提供行为
- 迪米特法则：只和直接朋友说话，避免 `a.getB().getC().doSomething()`
- 不要毫无节制地通过 getter/setter 暴露内部结构

## 错误处理
- 使用异常，不要使用返回码或错误标志
- 代码可能失败时，先写 `try-catch-finally`
- 在异常信息中提供上下文
- 不要返回 `null`，改为返回空集合或使用 Optional/Maybe
- 不要把 `null` 作为参数传入

## 类
- 小类应按职责衡量，而不是按行数衡量
- 单一职责原则：只有一个改变原因
- 高内聚：类变量被多数方法使用
- 低耦合：类之间依赖尽量少
- 开闭原则：对扩展开放，对修改关闭

## 单元测试
- 快速、独立、可重复、自我验证、及时（F.I.R.S.T.）
- 每个测试一个断言，或只验证一个概念
- 测试代码质量应与生产代码质量一致
- 测试名称要可读，清楚描述正在测试什么
- 遵循 Arrange-Act-Assert 模式

## 代码质量原则
- **DRY（Don't Repeat Yourself）**：不要重复
- **YAGNI（You Aren't Gonna Need It）**：不要为假设中的未来提前构建
- **KISS（Keep It Simple）**：避免不必要的复杂度
- **童子军规则**：让代码比你接手时更干净

## 应避免的代码坏味道
- 函数或类过长
- 重复代码
- 死代码（未使用的变量、函数、参数）
- 特性依恋（方法更关心别的类）
- 不恰当的亲密关系（类彼此了解过多）
- 过长的参数列表
- 原始类型偏执（过度使用原始类型而不是小对象）
- switch/case 语句（考虑使用多态）
- 临时字段（类变量只在某些时候才使用）

## 并发
- 将并发代码与其他代码隔离
- 限制同步/加锁数据的作用域
- 使用线程安全集合
- 保持同步区块尽量小
- 了解你的执行模型和原语

## 系统设计
- 将构建和使用分离，例如通过依赖注入
- 复杂对象创建时使用工厂、构建器
- 面向接口编程，而不是面向实现编程
- 优先组合而不是继承
- 设计模式只在它们简化问题时使用，不要为了炫技而使用

## 重构
- 持续重构，不要攒成大批量一次做完
- 重构前后都要保证测试通过
- 小步前进，每次只改一处
- 常见重构包括：提取方法、重命名、移动、内联

## 文档
- 自说明代码 > 注释 > 外部文档
- 公共 API 需要清晰文档
- 文档中要包含示例
- 文档尽量靠近代码，理想情况下就在代码里

---

**核心理念**：代码被阅读的次数是编写次数的 10 倍。优化可读性和可维护性，而不是追求花哨。