6.2 装备精炼：代码质量与工程习惯

6.2 装备精炼：代码质量与工程习惯

本节摘要：好代码的标准是别人能低成本改对它。本节从命名、函数边界、测试三处入手讲代码质量——每处给改前改后的真实对照——并给出个人阶段就能养成的工程习惯清单：格式化、提交纪律、小步提交。

技能树顶层第二问。副本阶段的目标是"能跑"，转职之后的标准立刻换轨："别人能不能安全地改你的代码"。这不是审美问题，是经济问题——代码读与改的时间，历来十倍于写的时间。

一、质量的第一性问题：为修改者而写

先确立判断标准。代码有两种失败：跑不起来，或跑起来但没人敢改。前者是正确性问题，第五章已解决；后者是质量问题，它的度量尺是修改成本——一个从没见过这段代码的工程师，理解它、安全地改动它、并确认没改坏，需要多久。

由此推出三条可操作的原则：

• 代码是写给人读的，机器只是顺便执行
• 任何"聪明"到需要读者停下来推理的写法，都默认有罪
• 检验质量的时刻不是你写完，而是你三个月后回来改

二、三个抓手：命名、边界、测试

质量是个大词，但个人阶段能立竿见影的抓手只有三个。

抓手一，命名说出意图。名字是零成本的文档。对照实例：

# 改前: 能跑, 但读者要逆向推理
def proc(d, k):
    v = d.get(k, 0)
    return v + 1

# 改后: 名字即注释, 函数体无需解释
def increase_count(counts, word):
    return counts.get(word, 0) + 1
​

改前的读者必须在大脑里执行一遍才能确认语义；改后名字直接给出。命名的下限标准：删掉注释后，读者仍能说出每个变量装着什么。

抓手二，函数只做一件事。"一件事"的判定标准是能否用一句不含"和"字的话描述这个函数。对照：

# 改前: 一件事? 三件事: 读文件 解析 汇总
def handle(path):
    lines = open(path).read().splitlines()
    items = [l.split(",") for l in lines if l.strip()]
    return sum(int(row[1]) for row in items)

# 改后: 各自可测, 各自可复用
def read_rows(path):
    return [l.split(",") for l in open(path).read().splitlines() if l.strip()]

def total_of(rows, col):
    return sum(int(row[col]) for row in rows)
​

拆分后每个函数都能被单独测试与复用，出错时定位范围也缩小到单个函数。个人阶段的经验值：函数超过一屏或参数超过四个，就该考虑拆。

抓手三，测试是行为说明书。测试不是负担，是把"这个函数应该怎么表现"写成可执行文档。以计数逻辑为例：

def test_increase_count():
    assert increase_count({}, "a") == 1        # 新键从零起
    assert increase_count({"a": 2}, "a") == 3  # 已有键累加
    assert increase_count({"a": 1}, "b") == 1  # 互不干扰

test_increase_count()
print("全部通过")
​

全部通过
​

三条断言写的就是三种行为约定。将来任何人改动这段代码，跑一遍测试就知道有没有破坏约定——这是"别人能安全地改你的代码"的机制保障。个人项目的起步规格：每个核心函数配三到五条断言，覆盖正常、边界、异常三类输入。

代码质量的投入产出

三、个人阶段就能养成的习惯清单

工程习惯不必等入职，个人项目就能启动四条：

1. 格式化自动化：保存即格式化（1.3 节配置过），风格之争从此归零
2. 提交纪律：每完成一个可验证的改动提交一次，说明写"做了什么、为什么"——Git 历史就是项目的时光机日志
3. 新代码配测试：只要求新写的核心函数有断言，不追溯旧代码——起步阻力最小
4. 删比加难，练习删：每次提交前扫一遍有没有死代码、重复块，删掉它们；克制"留着以后可能用上"的冲动，版本历史本来就是最好的仓库

四、案例：一次"为了加功能而先精炼"的重构

背景：小郑的记账脚本要加"按月汇总"，但她打开代码发现主函数近两百行，读写、解析、统计全缠在一起，不敢下手。

操作：她先做纯重构（不改行为）：按"读、解析、统计、输出"拆成四个函数，每个函数配三到五条断言测试；重构期间每拆一个函数就跑一次测试，全绿再拆下一个。半天后主函数只剩十行调度代码。然后加月度汇总——因为统计逻辑已独立成函数，新功能只是新增一个同级函数加两行调度，四十分钟完成。

结果：功能上线当天通过；两周后她又给统计函数加了"按类别汇总"，这次只花了二十分钟——精炼过的结构持续兑现。

解读：这次经历展示了精炼的正确时机感——不是为美而重构，是为即将到来的修改铺路。测试在其中的角色是安全网：没有断言兜底，拆分两百行函数的风险高到没人敢做；有了断言，每一步拆分都可验证。顺序也很重要：先测试锁定现状，再重构，最后加功能——这个"红绿重构"节奏正是业界测试驱动开发的日常形态。

变式：读别人的代码发现坏味道时同样适用——加测试、小步重构、保持每步绿灯。唯一的纪律是重构与加功能绝不混在一次提交里，否则回滚时分不清动因。

⚠️ 常见坑：在个人小项目上追求企业级架构——层层抽象、万物皆模式。质量三抓手的成本极低而收益立现；架构规范是团队规模问题，一个人的项目过度设计只会拖慢自己。

五、代码可读性的自检清单

三个抓手之外，日常自查可以用一份轻量清单。每次提交前扫一遍，十秒够用：

[ ] 删掉注释, 名字还能自解释吗
[ ] 最长的函数超过一屏了吗
[ ] 有重复出现的代码块(两处以上相同逻辑)吗
[ ] 未来的我读这段, 会在哪一行停下来皱眉
​

第四条是清单里最有威力的——它强制你切换到读者视角。具体操作：提交前把改动当作别人的代码读一遍，凡是让你停顿超过三秒的地方，就是需要注释、改名或拆分的地方。

清单刻意只放四条。可读性检查表可以很长，但长清单不会被真正执行；四条能在十秒内跑完的检查，胜过四十条躺在文档里的规范。这也呼应了 2.2 节的结论：清单越短，执行越稳。

本节要点回顾

• 质量即修改成本：好代码是别人能低成本改对的代码
• 命名说出意图：删掉注释读者仍知道每个变量装什么
• 一件事原则：一句话描述不含"和"，超一屏考虑拆
• 测试是行为说明书：核心函数配三五条断言，覆盖正常边界异常
• 先测试再重构后加功能：三步绝不混在同一次提交