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

有意义的命名

• 使用能体现意图的名称，说明它为什么存在
• 避免误导性命名和无意义区分，例如 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 倍。优化可读性和可维护性，而不是追求花哨。