clean-code-guard 注释与排版规范：基于 Clean Code 第 4、5 章的代码质量守则实战
【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills
本指南脱胎于 agentic-awesome-skills 仓库中clean-code-guard技能的参考文档 comments-and-formatting.md，系统讲解 Robert C. Martin《Clean Code》第 4 章（注释）与第 5 章（排版）在 AI 辅助编码与人工评审中的落地方法。读完本文，你将掌握一套可执行的注释取舍标准、五种垂直与水平排版规则，以及一份交付前的注释自查清单，可直接用于日常代码评审与 guard-pass 守门流程。
一、背景：这份规范在 clean-code-guard 技能中的定位
在 SKILL.md 中，clean-code-guard是一个对生成或修改的生产代码进行 Clean Code、SOLID、DRY/KISS/YAGNI 与 LLM 特有失败模式审查的守门技能。它提供三种工作模式：
- Guard-pass 模式（推荐）：在代码生成、编辑、重构或修复之后，对照本规范检查 diff 或目标文件，在呈现、提交或合并前修复违规；
- Live 模式：在用户明确要求、高风险编辑之前激活，写作过程中同步应用规则，交付前运行自查清单；
- Review 模式：按 review-checklist.md 的结构化清单走查目标文件，输出分级发现报告。
本参考文档对应 SKILL.md 中"始终应用的强制项"（Always-applied imperatives）第 5、6 条：
- 注释解释 why，绝不解释 what。删除任何转述其下方代码的注释；删除步骤编号脚手架注释；删除被注释掉的代码——版本控制已存在。（Clean Code 第 4 章）
- 匹配文件既有风格。在动手前阅读要编辑的文件以及至少一个相邻文件，镜像其大小写、导入顺序、错误处理、日志以及 HTTP/DB 客户端选择，不要引入第二种模式。
clean-code-guard是便携式指令技能，不依赖 MCP 服务器、网络、API Key 或脚本，任何支持SKILL.md加直接链接的 references/ 文件的运行时都可以使用；它也不替代项目的 linter、格式化器、类型检查器或测试运行器——机械验证交给项目工具，本规范负责代码质量与评审的"判断层"。
二、注释的根基法则："不要注释坏代码，重写它"
本规范开篇即给出核心原则：
"Don't comment bad code — rewrite it."
注释是代码未能表达意图时的失败补偿。每一条注释都是重命名或提取函数的候选对象——与其用注释解释一段混乱的逻辑，不如把逻辑改清晰，让代码本身"自解释"。
这条原则在 ai-failure-modes.md 中被进一步归类为 LLM 特有的第 4 号失败模式Comment pollution（注释污染）：逐行转述代码的注释、残留的步骤编号脚手架注释、转述函数签名的文档注释，都是 AI 生成代码最常见的"美观"败笔。因此这份规范对 AI 辅助编码尤其重要——LLM 倾向于"发射"多余注释来显得有条理，而守门技能的任务就是把这些注释清理掉。
三、C1：值得保留的注释（屈指可数）
规范给出了一份"能挣得自身位置"的短清单。注意每一类都有明确的非显而易见理由：
| 类型 | 说明 | 示例 |
|---|---|---|
| 法律头注 | 许可证样板、版权声明 | 文件头的 license 块 |
| 意图（Intent） | 解释为什么做出某决策，且该决策非显而易见 | // Use exponential backoff to avoid hammering the rate limiter during retries. |
| 后果警告（Warnings of consequences） | 提醒后续维护者某个调用点有特殊约束 | // This function is called during transaction commit; do not raise. |
| TODO | 节制使用，必须带跟踪工单引用 | // TODO(JIRA-1234): switch to streaming once API supports it. |
| 公共 API 文档 | 文档字符串记录契约（前置条件、后置条件、异常），而非函数体 | 见下文 C3 的charge示例 |
| 放大强调（Amplification） | 提醒读者注意不显眼的细节 | # The+ 1accounts for the inclusive end of the range; see RFC §3.2. |
观察这六类的共同点：它们解释的都是"代码之外的事实"——许可、历史决策、调用上下文、外部规范引用、契约边界——而不是"代码本身在做什么"。这正是区分好注释与坏注释的试金石。
四、C2：见到就删的注释（零容忍清单）
与保留清单相对的是一份"见到就删"清单，每条都附带删除理由：
- 转述代码的注释：
// increment counter by one出现在counter += 1上方。注释零信号增益，却制造了两处需要维护的内容——代码改了注释却没改，就会变成新的谎言。 - 噪音注释：
# default constructor、# getter、# returns the day of month。这类注释不传达任何读者不知道的信息。 - 横幅注释：
# ====== USER FUNCTIONS ======。需要用横幅分隔的文件应拆分为类或模块，而不是用注释画分割线。 - 闭合花括号注释：
} // end of for loop。如果必须靠这种注释才能跟上控制流，说明函数太长，应该提取。 - 署名与日志式注释：
# Updated by Bob on 2023-04-01 to fix bug #42。版本控制系统已经完整记录这些信息，写在代码里只会腐化。 - 被注释掉的代码：直接删除。需要时 git 里有。被注释的代码块是"有毒"的——读者无法判断它们是否可信、是否还在生效。
Step 1/Step 2脚手架：这是 LLM 生成的常见残留物。每一步都应该是带名字的函数调用，函数名本身就提供了结构，不需要编号注释。
最后一条对 AI 辅助编码有特殊意义：LLM 在回答多步问题时习惯输出Step 1: ...、Step 2: ...的注释骨架，而规范要求把这些脚手架全部删除，把步骤沉淀为命名良好的函数。
五、C3：文档字符串纪律——记录契约，不转述签名
转述函数签名的文档注释是噪音。规范给出了正反例：
坏：
add(a, b) // Adds a and b and returns the result. return a + b好：
add(a, b) return a + b而一份文档注释要"挣得自己的位置"，就必须记录契约：可以传入什么、可能返回什么、会抛出什么错误，以及任何非显而易见的副作用。
好：
// Charge a payment source. // Returns: charge identifier. // Raises: CardDeclined for decline failures; PaymentProviderError otherwise. // Side effect: writes an audit record on success. charge(paymentSourceId, amountCents)对比两组示例可以提炼出判据：描述"输入→输出"的转述一律删除；描述"约束、异常、副作用"的契约保留。这与 naming-and-functions.md 中"优先用异常而非返回码"（F9）、"命令与查询分离"（F7）的规则相互呼应——清晰的契约文档配合清晰的函数边界，才能让调用者在不读函数体的情况下安全使用。
六、排版五规则：让结构通过空白表达
《Clean Code》第 5 章关于排版的要点被提炼为 Fmt1～Fmt5 五条规则，分为垂直与水平两个维度。
Fmt1：垂直开放分隔概念
概念之间用空行分隔；紧密耦合的代码块内部不插空行。眼睛把空行当作边界——垂直开放度（vertical openness）直接决定读者能否一眼看出代码的分组结构。
Fmt2：垂直密度暗示关联
属于一起的代码应该放在一起。变量声明在其使用处 30 行之外，是一个坏味道（smell）。垂直密度（vertical density）暗示两个代码片段之间的关联强度。
Fmt3：垂直距离——就近原则与逐步下行
- 变量靠近使用处声明，而不是像 C 风格那样堆在函数顶部；
- 调用者位于被调用者之上：自上而下的阅读顺序，高层函数在前、它调用的辅助函数紧随其后，即 naming-and-functions.md F4 的step-down rule（逐步下行规则）；
- 概念相关的函数彼此相邻：如果
parse_invoice与validate_invoice是同级函数，就应挨在一起，而不是分处文件两端。
Fmt4：水平密度——空格与行长
- 赋值与比较运算符两侧加空格：
x = 1、if x == 1； - 函数名与左括号之间不加空格：
f(x)而非f (x)； - 行长：传统 80 列，≤100～120 可接受，超过 120 属于粗心。
Fmt5：匹配你正在编辑的文件
这是最常见的跨切面违规：在一个已有风格的文件里引入新风格。
- 文件用 snake_case，就不要引入 camelCase；
- 文件用双引号，就不要引入单引号；
- 文件按字母序排序导入，就不要在末尾追加；
- 项目已有 HTTP 客户端、数据库封装或日志辅助函数，就复用而不是另起炉灶。
团队规则优先于个人偏好。先读文件，再动手写。这条规则在 SKILL.md 中被提升为强制项第 6 条"Read before write"（先读后写），并在第 22 条中要求：在不熟悉的仓库中写代码前，阅读将要编辑的文件、至少一个相邻文件以及任何项目规则文件（CLAUDE.md、AGENTS.md、README 的 conventions 章节），复用项目已有的辅助函数、错误类型与日志方式。
七、排版规则背后的 AI 视角
排版规则 Fmt1～Fmt5 在 ai-failure-modes.md 中同样有对应失败模式：第 10 号Inconsistency with surrounding code（与周边代码不一致）——在 camelCase 文件中引入 snake_case、在仓库已有 HTTP 客户端时新建一个、已有错误类型分类体系时新增一种、引入新的日志风格。规范给出的生产环境修复方式与 Fmt5 完全一致：强制 Agent 在动手前阅读仓库局部约定。
八、交付前自查清单：注释与排版的六步走
规范在文末提供了一份发货前自查清单，可逐条勾选：
- 逐条检查你添加的每条注释：它解释的是why吗？如果解释的是what，删除。
- 逐条检查你添加的每个文档注释：它在转述签名吗？删除转述，只保留契约文档。
- 有被注释掉的代码吗？删除。
- 有
Step 1、Step 2、First, ...、Then, ...之类的脚手架注释吗？删除。 - 变量是声明在使用处附近，而不是堆在顶部吗？
- 大小写、引号、导入顺序是否与文件既有风格一致？
这份清单可以无缝并入 SKILL.md 的 "Self-check before delivery" 主清单（第 3 项："对于新注释，问：它解释why吗？如果解释what，删除它"）。它也可以直接当作 Review 模式中 review-checklist.md Section B（comments & formatting）的检查工具：逐项标记"转述代码的注释、被注释掉的代码块、步骤编号脚手架、无契约的签名转述文档、与周边文件风格不一致"。
九、与相邻参考文档的分工
本文件是clean-code-guard参考体系中的一环，与其它参考文件各司其职：
- naming-and-functions.md——《Clean Code》第 2、3 章：命名与函数。本文件 Fmt3 引用的 step-down rule 源自其 F4，命令/查询分离对应其 F7；
- solid.md——SOLID 五原则；
- dry-kiss-yagni.md——DRY/KISS/YAGNI，其中"错误的抽象比重复更糟"（Sandi Metz）与"重复是万恶之源"共同构成注释规范背后"提取优先于注释"的依据；
- ai-failure-modes.md——LLM 生成坏代码的 15 种系统化模式，注释污染（#4）与风格不一致（#10）与本文件直接相关；
- sources.md——所有外部引用的集中书目，需要核对或引用来源时阅读。
整体阅读路径建议：先读 ai-failure-modes.md 了解 LLM 特有的高危模式，再读本文件掌握注释与排版的具体判据，最后在评审时按 review-checklist.md 的 Section B 落地执行。
十、把规范变成习惯
注释与排版是代码评审中最容易被"机械规则"覆盖、却也最容易被 AI 工具系统性破坏的层面。clean-code-guard给出的不是一份风格指南，而是一套可执行的判断框架：
- 注释上：只保留法律头注、意图、后果警告、带工单的 TODO、公共 API 契约文档与放大强调；见到转述、噪音、横幅、闭合花括号、署名日志、注释掉的代码与
Step N脚手架，一律删除； - 排版上：空行分隔概念、紧邻暗示关联、变量靠近使用处、调用者在上被调用者在下、水平留白规范、行长设限，并以"匹配文件既有风格"作为最终兜底；
- 流程上：在 guard-pass、live、review 三种模式下反复执行自查清单，让"每条注释都能回答 why"成为肌肉记忆。
记住规范反复强调的那句话："Don't comment bad code — rewrite it."注释不是兜底手段，代码本身的清晰表达才是第一优先级。
【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
