知识库

Clean Code（代码整洁之道）

8分钟阅读

Clean Code（代码整洁之道）

作者: Robert C. Martin (Uncle Bob)
系列: The Object Mentor Series
核心格言: Writing clean code is what you must do in order to call yourself a professional.

书籍概要

《Clean Code》是软件工程领域的经典著作，由” Uncle Bob” Martin撰写。本书系统阐述了如何编写整洁、可读、可维护的代码，强调编程不仅是技术活动，更是艺术和 craftsmanship。

书的核心观点：脏代码的成本远超想象。维护脏代码的团队效率会降低50%以上，而整洁代码能够显著降低认知负担，提高开发速度。

核心主题

1. 有意义的命名 (Meaningful Names)

核心原则: 名称应该揭示意图

  • Use Intention-Reealing Names: int daysSinceCreation 比 int d 更好
  • Avoid Disinformation: 不要用 hackedList 暗示list被黑，除非真的如此
  • Make Meaningful Distinctions: 不要用 a1, a2 这样无意义的编号
  • Avoid Mental Mapping: 不要让读者在脑中将 ProductSpecification 映射为 ProductSpec
  • Use Solution Domain Names: 用领域内术语命名
  • Use Problem Domain Names: 反映业务概念的命名

关键规则: Pick One Word per Concept — 一个概念用一个词表示，避免同义词混用

2. 函数 (Functions)

核心原则: 函数应该小、做一件事、抽象层级一致

  • Small!: 函数应该尽可能小（2-3行是理想状态，不超过5行）
  • Do One Thing: 函数应该只做一件事，且只做这一件事
  • One Level of Abstraction per Function: 函数内的所有操作应在同一抽象层级
  • The Stepdown Rule: 阅读代码应从上到下，每层抽象逐步展开
  • Use Descriptive Names: 函数名应描述其做了什么
  • Function Arguments: 最少参数，最好0-2个，避免三元组
  • Have No Side Effects: 避免隐藏的副作用
  • Command Query Separation: 查询（返回结果）和命令（改变状态）应该分离
  • Prefer Exceptions to Returning Error Codes: 使用异常而非返回错误码
  • Don’t Repeat Yourself (DRY): 消除重复代码

3. 注释 (Comments)

核心原则: 注释不能替代糟糕的代码，好代码本身就是最好的注释

Good Comments:

  • Legal comments
  • Informative comments
  • Explanation of intent
  • Clarification
  • Warning of consequences
  • TODO comments
  • Amplification

Bad Comments:

  • Mumbling — 含糊不清的注释
  • Redundant comments — 与代码重复的注释
  • Misleading comments — 误导性注释
  • Mandated comments — 强制性的注释模板
  • Journal comments — 历史记录
  • Noise comments — 噪音
  • Scary noise — 可怕的噪音
  • Commented-out code — 注释掉的代码

关键洞察: “Comments are, at best, necessary evils.” — 注释最多是必要的邪恶，最好的代码不需要注释。

4. 格式化 (Formatting)

核心原则: 格式化是一种社会契约，体现团队规范

  • Vertical Formatting: 概念之间保持垂直开放，相关代码保持垂直密度
  • Horizontal Formatting: 控制代码行的宽度，对齐变量声明
  • Team Rules: 团队应统一格式化规则
  • Uncle Bob’s Rules:
    • 代码行不超过80-100字符
    • 函数长度不超过屏幕高度
    • 相关概念紧密放置

5. 对象与数据结构

核心原则: 抽象vs数据结构，Law of Demeter

  • Data Abstraction: 隐藏实现细节
  • Data/Object Anti-Symmetry: 对象暴露行为隐藏数据，数据结构暴露数据隐藏行为
  • The Law of Demeter: 只与直接朋友通信，减少火车残骸（a.b.c.d）
  • Data Transfer Objects: 简单数据结构用于传递数据

6. 错误处理

核心原则: 使用异常而非错误码

  • Use Exceptions Rather Than Return Codes
  • Write Try-Catch-Finally Statement First
  • Use Unchecked Exceptions
  • Provide Context with Exceptions
  • Define Exception Classes in Terms of a Caller’s Needs
  • Define the Normal Flow
  • Don’t Return Null
  • Don’t Pass Null

7. 边界 (Boundaries)

核心原则: 清理第三方代码的边界

  • Using Third-Party Code
  • Learning log4j
  • Clean Boundaries

8. 单元测试 (Unit Tests)

核心原则: TDD三定律，测试应该干净、快速、独立

  • The Three Laws of TDD:

    1. 在编写不能通过的单元测试之前，不能编写生产代码
    2. 只编写刚好不能通过的单元测试，编译失败即为失败
    3. 只编写刚好能通过当前失败测试的生产代码

  • F.I.R.S.T. 原则:

    • Fast — 快速
    • Independent/Isolated — 独立
    • Repeatable — 可重复
    • Self-validating — 自验证
    • Timely — 及时

  • Clean Tests:

    • One Assert per Test
    • Single Concept per Test
    • Readable
    • Domain-Specific Testing Language
    • A Dual Standard (测试代码也要整洁)

关键概念

概念描述
Boy Scout Rule离开营地时要比来时更干净 — 每次提交代码都要比之前更整洁
SOLIDSingle Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
DRYDon’t Repeat Yourself — 消除重复
KISSKeep It Simple, Stupid — 保持简单
YAGNIYou Aren’t Gonna Need It — 不要过度设计
Stepdown Rule阅读代码时，每个函数都应该比调用它的函数低一个抽象层级

重要数据/结论

  1. 脏代码成本: 维护团队中，超过一半的时间花在理解已有代码上
  2. 函数大小: 理想函数长度是2-3行，最大不超过5行
  3. 参数数量: 0参数函数最优，1-2参数可接受，避免三元组及以上
  4. 测试速度: 单元测试应该秒级执行，否则开发者不会运行它们
  5. 命名重要性: 代码中70%的复杂度来源于糟糕的命名

行动点

  • 审查现有代码库中的函数大小，将过长的函数拆分
  • 检查变量命名是否揭示意图
  • 删除冗余注释和注释掉的代码
  • 确保每个函数只做一件事
  • 遵循F.I.R.S.T.原则编写测试
  • 应用Boy Scout Rule：每次提交都让代码比之前更整洁

关联笔记

笔记生成日期: 2026-09-02 | 处理方法: PDF文本提取 (pdf-inspector)

关系图谱

反向链接