Logo
刘常宁
搜索

代码整洁之道

合集AI合集
发布时间2026/06/26
浏览0 次

一、整洁代码的核心定义

  1. 可读性优先，逻辑清晰、意图直观，无需大量注释辅助理解
  2. 单一职责，函数/类只做一件事，抽象分层明确
  3. 可测试、低耦合、高内聚，修改一处不会连锁破坏其他模块
  4. 遵循童子军规则：离开代码时，比接手时更干净，持续小步重构
  5. 拒绝“能跑就行”，烂代码会导致Bug、迭代、排障成本指数级上涨

二、有意义的命名

1. 基础准则

  • 名副其实，见名知意，无需注释解释变量/函数用途
  • 避免误导accountList 必须是列表，不能用模糊词 datainfotemp
  • 杜绝无意义区分user1user2 不如 vipUsernormalUser
  • 使用可搜索名称：拒绝单字母变量、魔法数字，常量统一命名
  • 慎用易混淆字符l1O0，避免视觉歧义

2. 分类命名规范

  • 类/对象：名词、名词短语 OrderUserAccount
  • 函数/方法：动词短语 calculateTotal()getUserInfo()
  • 布尔变量：带判定语义 isExpiredhasPermission
  • 常量：全大写下划线 MAX_RETRY_COUNT

3. 避坑要点

  • 不使用匈牙利标记法（类型前缀）
  • 统一术语：全程只用 user 或 customer，不要混用
  • 长描述名称 > 短模糊名称，长名称 > 冗余注释

三、编写优质函数（第二章）

1. 黄金规则

  1. 短小，再短小：控制在20行内，缩进层级不超过1~2层
  2. 只做一件事：一个函数只完成单一抽象层级逻辑
  3. 自上而下阅读：主逻辑在前，辅助私有函数紧随其后

2. 参数规范

  • 参数越少越好：0个最优，1个次之，2个谨慎，≥3个必须重构
  • 禁止布尔标识参数save(true)），拆分为 saveDraft() / savePublish()
  • 禁用输出参数，优先使用返回值传递结果

3. 函数行为约束

  • 无副作用：承诺只做查询就不修改全局/外部对象状态
  • 命令查询分离：函数要么修改数据（命令），要么返回数据（查询），不能同时
  • 异常替代错误码，统一异常处理逻辑

四、注释规范（第三章）

核心原则：好代码自带解释，注释是补救手段，而非标配

1. 允许保留的注释

  • 版权、法律声明
  • 复杂业务规则、非常规性能优化说明
  • 边界异常、特殊兼容说明
  • 待办 TODO、风险警告注释

2. 必须删除的垃圾注释

  • 重复代码语义// 循环i// 定义订单变量
  • 过期失效注释（代码逻辑已修改，注释未同步）
  • 分块分隔、冗余废话注释
  • 代码块注释掉的废弃代码（直接删除）

五、代码格式与排版（第四章）

1. 垂直排版

  • 逻辑分组空行分隔，无关代码拉开间距
  • 变量就近定义，调用函数放在被调用函数上方（报纸阅读顺序）
  • 公共方法在前，私有工具方法紧随其后

2. 水平排版

  • 运算符两侧统一空格，函数名与左括号无空格
  • 统一缩进，禁止混合制表符/空格
  • 团队统一一套格式化规范，个人风格服从团队标准

六、对象与数据结构（第五章）

1. 对象 vs 数据结构（核心对立）

  1. 对象（面向对象）：隐藏内部数据，对外暴露行为；新增子类容易，新增函数难
  2. 数据结构（过程式/DTO）：直接暴露字段，无复杂行为；新增函数容易，新增数据字段难

2. 迪米特法则（最少知识原则）

模块不能深入访问多级成员 a.b.c.getInfo()，禁止和“陌生人”交互；仅允许调用：自身、入参对象、创建的实例、全局变量

3. DTO数据传输对象

仅存放公共字段，无业务逻辑，用于接口、数据库数据传输场景

七、优雅错误处理（第六章）

  1. 优先异常，抛弃返回错误码，分离业务逻辑与异常分支
  2. 绝不返回/传递 null：
    • 集合返回空集合，对象使用空对象模式、Optional包装
    • 避免全链路无休止判空，减少空指针风险
  3. try-catch 独立拆分，只捕获对应业务异常，禁止超大块捕获所有错误
  4. 自定义业务异常，异常信息携带操作场景、失败原因，方便定位
  5. 不要吞异常，捕获后必须记录日志或向上抛出

八、第三方代码边界管理（第七章）

  1. 第三方SDK/框架封装适配层，隔离外部API，业务代码不直接依赖外部接口
  2. 边界层统一转换数据、异常，第三方版本升级仅修改适配层，不污染业务
  3. 为边界代码编写专属单元测试，验证第三方行为符合预期

九、整洁单元测试（第八章）

1. FIRST 测试五原则

  • Fast：测试执行速度快，频繁运行无等待
  • Independent：用例互不依赖，执行顺序不影响结果
  • Repeatable：任意环境（本地/服务器）执行结果一致
  • Self-validating：自动断言校验，不用人工查看日志判断成败
  • Timely：生产代码前编写测试（TDD）

2. TDD 三定律

  1. 不写无法通过的单元测试，就不编写业务代码
  2. 只编写刚好失败的最小单元测试
  3. 只编写刚好通过当前失败测试的最小业务代码

3. 测试代码规范

测试和生产代码同等重要，遵守整洁命名、短小、单一职责；每个测试只验证一个逻辑点，命名清晰表达测试场景

十、类设计规范（第九章）

  1. 类要短小，更短小；衡量标准是职责数量，而非代码行数
  2. 单一职责SRP：一个类只有一个修改理由，只负责一类业务逻辑，拒绝“上帝类”
  3. 高内聚：类内方法尽量共享成员变量，变量被多数方法使用
  4. 依赖管理：减少外部依赖，使用依赖注入降低耦合

十一、SOLID 五大面向对象设计原则（全书架构核心）

S - 单一职责 SRP

类/模块仅有一个修改理由，一个职责对应一个类

O - 开闭原则 OCP

对功能扩展开放，对已有稳定代码修改关闭；通过抽象、多态新增逻辑，不改动旧代码

L - 里氏替换 LSP

子类实例可以完全替换父类，程序行为不产生异常；继承不能破坏父类原有逻辑

I - 接口隔离 ISP

客户端不依赖无用接口，拆分细粒度专用接口，拒绝庞大万能接口

D - 依赖倒置 DIP

高层业务模块依赖抽象接口，不依赖底层具体实现；抽象不依赖细节，细节依赖抽象

十二、迭代、重构与简单设计（第十章）

1. 简单设计四原则（优先级从高到低）

  1. 全部测试可运行
  2. 消除代码重复（DRY）
  3. 表达清晰，命名、分层直观易懂
  4. 减少类、方法数量，不过度抽象

2. 重构准则

  • 持续小范围重构，不堆积大规模重构任务
  • 重构前保证单元测试全覆盖，重构后全量跑测
  • 童子军规则：每次修改顺带清理周边劣质代码
  • Later Equals Never：不要写“以后再优化”的技术债务

十三、并发编程整洁规范（补充章节）

  1. 分离并发与业务逻辑，并发代码单独封装
  2. 限制共享可变对象，最小化锁范围
  3. 同步逻辑短小，避免锁内执行耗时操作
  4. 为并发场景编写专用测试，模拟多线程竞争

十四、系统级整洁设计

  1. 分层架构，各层职责隔离，单向依赖
  2. 依赖注入统一管理外部资源，避免硬编码创建实例
  3. 区分业务领域代码与基础设施代码（数据库、缓存、MQ）
  4. 全局配置统一收口，拒绝分散硬编码常量

核心

  1. 命名见意，函数短小，一事一函数
  2. 注释少而精，排版统一分层清晰
  3. 不返回null，异常替代错误码
  4. 第三方做适配隔离，测试遵循FIRST
  5. 类守单一职责，架构遵循SOLID
  6. 持续重构，代码越迭代越干净
  7. 低耦合高内聚，可读优先