Clean Code(整洁代码)

整洁代码把意图、边界和约定表达清楚,让维护者能够理解并检查修改的影响。短函数、命名和统一格式是手段,正确行为与可维护性才是目标。

一句话定义

整洁代码把意图、边界和约定表达清楚,让维护者能够理解并检查修改的影响。短函数、命名和统一格式是手段,正确行为与可维护性才是目标。

为什么重要

  • 代码被读的次数远多于被写的次数。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 + 格式化器) 同一项目混用三种命名风格
图 1

“童子军规则”:离开营地时让它比来时更干净——每次提交顺手改善一点,而不是攒成“大重写”。

可运行示例

同一个功能的两种写法,并用断言检查给定样例的行为一致(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 持续遵守。

延伸阅读

理解检查

拆成更多小函数后,调用者必须来回跳转才能看懂,这算改善吗?

参考答案:未必。应比较意图是否更清楚、变化是否更集中,以及阅读和测试成本是否降低。

核验与复现

核验日期:2026-10-14。示例状态:运行通过。本轮日志:08_clean_code.py。

配套代码与核验资料

继续浏览基础 返回知识 →返回顶部 ↑
本篇目录
教程图解100%
教程图解