代码质量是什么

「能跑」不等于「好维护」。在 CodeRoadMap 里，backend 的 Service、platform 的 React 组件、content 里的 Markdown 都会随时间增长；若只追求功能交付，六个月后改一行逻辑可能要读遍半个仓库。代码质量 是把可读性、可测性、可演进性当作日常交付的一部分，而不是上线后的补救。

学习目标

• 说清代码质量的三个核心维度：可读、可测、可演进
• 理解质量是工程文化，而非个人「洁癖」
• 知道本 track 与 git-essentials、testing-essentials 的分工

三个维度

维度	含义	反例
可读性	他人（含未来的你）能快速理解意图	500 行方法、无意义缩写
可测性	逻辑可隔离、可断言	静态工具类里硬编码 HTTP
可演进性	改需求不必推倒重来	复制粘贴三份相似校验

可读性降低 认知成本；可测性提供 回归安全网；可演进性决定团队能否 持续交付 而不是「不敢动老代码」。

质量 ≠ 完美

常见误区：

• 过度设计：为假想需求抽象三层接口
• 零注释崇拜：命名差却拒绝写一句业务说明
• 覆盖率迷信：100% 行覆盖但断言无意义

健康标准是：在合理成本下，让下一次改动更便宜。这与 ai-coding-essentials 里「AI 加速写码、人负责质量」一致——速度可以借工具，责任不能外包。

工程文化

质量靠纪律落地：

1. 小步提交 → 见 git-essentials
2. Review 互检 → 下一课 cq-reviews
3. 测试守护 → testing-essentials
4. 规范一致 → 本 track 后续 cq-style

Spring 项目里分层、DTO、异常处理也影响质量，可对照 spring-boot-essentials 的 sb-layer 与 sb-validation。

练习

• 打开 backend 任意 Service，用 30 秒向同伴解释「这个方法做什么」（测可读性）
• 在 全栈路线图 找到 Code Quality 相关节点
• 列出你最近改过的文件里，哪一处「下次再改会最头疼」

小结