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、格式化器、类型检查器或测试运行器——机械验证交给项目工具本规范负责代码质量与评审的判断层。二、注释的根基法则不要注释坏代码重写它本规范开篇即给出核心原则Dont 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 章关于排版的要点被提炼为 Fmt1Fmt5 五条规则分为垂直与水平两个维度。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 列≤100120 可接受超过 120 属于粗心。Fmt5匹配你正在编辑的文件这是最常见的跨切面违规在一个已有风格的文件里引入新风格。文件用 snake_case就不要引入 camelCase文件用双引号就不要引入单引号文件按字母序排序导入就不要在末尾追加项目已有 HTTP 客户端、数据库封装或日志辅助函数就复用而不是另起炉灶。团队规则优先于个人偏好。先读文件再动手写。这条规则在 SKILL.md 中被提升为强制项第 6 条Read before write先读后写并在第 22 条中要求在不熟悉的仓库中写代码前阅读将要编辑的文件、至少一个相邻文件以及任何项目规则文件CLAUDE.md、AGENTS.md、README 的 conventions 章节复用项目已有的辅助函数、错误类型与日志方式。七、排版规则背后的 AI 视角排版规则 Fmt1Fmt5 在 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 Bcomments formatting的检查工具逐项标记转述代码的注释、被注释掉的代码块、步骤编号脚手架、无契约的签名转述文档、与周边文件风格不一致。九、与相邻参考文档的分工本文件是clean-code-guard参考体系中的一环与其它参考文件各司其职naming-and-functions.md——《Clean Code》第 2、3 章命名与函数。本文件 Fmt3 引用的 step-down rule 源自其 F4命令/查询分离对应其 F7solid.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成为肌肉记忆。记住规范反复强调的那句话Dont 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），仅供参考 clean-code-guard 注释与排版规范：基于 Clean Code 第 4、5 章的代码质量守则实战
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、格式化器、类型检查器或测试运行器——机械验证交给项目工具本规范负责代码质量与评审的判断层。二、注释的根基法则不要注释坏代码重写它本规范开篇即给出核心原则Dont 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 章关于排版的要点被提炼为 Fmt1Fmt5 五条规则分为垂直与水平两个维度。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 列≤100120 可接受超过 120 属于粗心。Fmt5匹配你正在编辑的文件这是最常见的跨切面违规在一个已有风格的文件里引入新风格。文件用 snake_case就不要引入 camelCase文件用双引号就不要引入单引号文件按字母序排序导入就不要在末尾追加项目已有 HTTP 客户端、数据库封装或日志辅助函数就复用而不是另起炉灶。团队规则优先于个人偏好。先读文件再动手写。这条规则在 SKILL.md 中被提升为强制项第 6 条Read before write先读后写并在第 22 条中要求在不熟悉的仓库中写代码前阅读将要编辑的文件、至少一个相邻文件以及任何项目规则文件CLAUDE.md、AGENTS.md、README 的 conventions 章节复用项目已有的辅助函数、错误类型与日志方式。七、排版规则背后的 AI 视角排版规则 Fmt1Fmt5 在 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 Bcomments formatting的检查工具逐项标记转述代码的注释、被注释掉的代码块、步骤编号脚手架、无契约的签名转述文档、与周边文件风格不一致。九、与相邻参考文档的分工本文件是clean-code-guard参考体系中的一环与其它参考文件各司其职naming-and-functions.md——《Clean Code》第 2、3 章命名与函数。本文件 Fmt3 引用的 step-down rule 源自其 F4命令/查询分离对应其 F7solid.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成为肌肉记忆。记住规范反复强调的那句话Dont 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），仅供参考