一句话定义
整洁代码把意图、边界和约定表达清楚,让维护者能够理解并检查修改的影响。短函数、命名和统一格式是手段,正确行为与可维护性才是目标。
为什么重要
- 代码被读的次数远多于被写的次数。PEP 8 开篇即引用 Guido 的观点:“代码被阅读的频率远高于被编写的频率”:https://peps.python.org/pep-0008/
- 表达清楚的代码通常更便于评估修改影响:难懂的代码让每次改动都提心吊胆,bug 也躲在难懂的地方。
- AI 时代更重要:AI 能飞快生成代码,人类的主要工作变成“读和审”。可读性差的代码,人审不动,AI 也更容易改错。
使用边界
函数长度、参数数量等阈值是团队启发式规则,不是正确性定理。示例中的断言只覆盖列出的输入,不能证明所有可能输入上的行为完全等价。
原理 / 图解
下面列出几条常见实践;具体阈值与风格应服从语言特点、公共接口和团队约定。可参考 PEP 8。
| 方面 | 做法 | 反例 |
|---|---|---|
| 命名 | 名字回答“是什么、为什么” | d、tmp2、data_list_new |
| 函数 | 短、只做一件事、参数少 | 300 行、7 个参数、带布尔开关参数 |
| 注释 | 解释“为什么”,而不是复述“做什么” | i += 1 # i 加 1 |
| 结构 | 早返回,减少嵌套 | 五层 if 嵌套 |
| 一致性 | 遵守团队风格(Python 用 PEP 8 + 格式化器) | 同一项目混用三种命名风格 |
“童子军规则”:离开营地时让它比来时更干净——每次提交顺手改善一点,而不是攒成“大重写”。
可运行示例
同一个功能的两种写法,并用断言检查给定样例的行为一致(Python 3.15.0 一稿运行记录):
# 文件:examples/08_clean_code.py
# Clean Code:同一逻辑的"难读版"与"整洁版",并用断言证明行为一致
def f(l, t):
r = []
for i in l:
if i[1] > t and i[2] == 1:
r.append(i[0])
return r
from dataclasses import dataclass
ACTIVE = 1
@dataclass
class Employee:
name: str
salary: int
status: int
def names_of_active_employees_earning_over(employees: list[Employee], threshold: int) -> list[str]:
"""返回薪资高于 threshold 的在职员工姓名。"""
return [e.name for e in employees
if e.salary > threshold and e.status == ACTIVE]
raw = [("ann", 9000, 1), ("bob", 12000, 0), ("cat", 15000, 1)]
emps = [Employee(*row) for row in raw]
assert f(raw, 8000) == names_of_active_employees_earning_over(emps, 8000)
print(names_of_active_employees_earning_over(emps, 8000))
print("两版行为一致,但第二版不需要注释也能读懂")
一稿留存输出:
['ann', 'cat']
两版行为一致,但第二版不需要注释也能读懂
第二版更长,但读名字就知道它在干什么:整洁不等于短。
常见误区
- “整洁 = 越短越好”:一行塞进三层推导式的“聪明代码”是可读性的敌人。
- 把书里的规则当法律:如“函数不超过 N 行”。Clean Code 一书的部分建议(极短函数、大量小类)在社区有争议,例如 qntm 的长文 It's probably time to stop recommending Clean Code(2020):https://qntm.org/clean 。应理解原则背后的目的,再结合语言和团队习惯取舍。
- 手工调格式:格式问题交给工具。Ruff 可同时做 lint 与格式化:https://docs.astral.sh/ruff/
- 注释越多越好:过时的注释比没有注释更糟。好的命名能替代大部分“做什么”的注释。
与 AI 开发的关系
- AI 生成的代码常见“不整洁”:变量名泛化(
result、data)、重复代码、过度防御的try/except。审查 AI 代码时把 Clean Code 清单当检查表。 - 在提示词里写明规范:如“遵循 PEP 8,函数职责清楚,使用描述性命名,加类型提示”,或在项目里放规则文件(如
AGENTS.md、编辑器规则文件)让 AI 持续遵守。
延伸阅读
- PEP 8 – Python 代码风格指南:https://peps.python.org/pep-0008/
- Google Python 风格指南:https://google.github.io/styleguide/pyguide.html
- Robert C. Martin,《代码整洁之道》(2008)
- qntm, It's probably time to stop recommending Clean Code:https://qntm.org/clean
理解检查
拆成更多小函数后,调用者必须来回跳转才能看懂,这算改善吗?
参考答案:未必。应比较意图是否更清楚、变化是否更集中,以及阅读和测试成本是否降低。
核验与复现
核验日期:2026-10-14。示例状态:运行通过。本轮日志:08_clean_code.py。
配套代码与核验资料