Clean Code 原则

核心命题：代码是写给人看的，顺便给机器执行——命名、函数、注释三大基石，跨语言通用。

---

01. 案例引入

一个真实事故：一个命名不当的变量导致团队花 3 天排查 Bug；一个 500 行的函数没人敢改，最终选择重写。

---

02. 命名

• 有意义的命名：d → elapsedTimeInDays
• 避免误导：accountList 不是 List 就别叫 List
• 可搜索的名字：单字母只用于循环局部变量
• 类名用名词，方法名用动词

跨语言对照

维度	Java	Go	Python	JS
类名	PascalCase	PascalCase	PascalCase	PascalCase
方法	camelCase	camelCase	snake_case	camelCase
常量	UPPER_SNAKE	UPPER_SNAKE	UPPER_SNAKE	UPPER_SNAKE

---

03. 函数

• 短小：一个函数只做一件事
• 参数尽量少：0参最好，1参数优，2参数可接受，3+应封装
• 无副作用：函数要么做事，要么返回，不要两个都做
• 一个抽象层级

---

04. 注释

• 好的注释：解释 Why 而非 What，TODO，警告后果
• 坏的注释：冗余注释、被注释掉的代码、日志式注释
• 能用代码表达的就不要用注释

---

05. 格式与组织

• 垂直格式：相关概念靠近，变量声明靠近使用处
• 水平格式：一行不超过 120 字符
• 团队统一：用 Linter + Formatter 强制，不靠人肉

---

06. 一句话总结

好代码 = 不需要注释就能读懂的命名 + 单一职责的函数 + 自动化的格式。Clean Code 不是教条，是让团队协作成本降低 10 倍的工程纪律。