agentic-awesome-skills 的 clean-code-guard：命名与函数的十六条铁律实战指南

AI 技能AI 插件【免费下载链接】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点击查看免费下载本指南以 clean-code-guard 技能的核心参考文档 naming-and-functions.md 为主体系统讲解罗伯特·马丁《代码整洁之道》Clean Code第 2 章有意义的命名与第 3 章函数在 AI 代码生成与代码审查场景下的落地准则。读完本文你将掌握命名六戒N1–N6与函数十律F1–F10的完整判据、可复制的正反例以及如何在 guard-pass守卫检查、live实时书写、review审查三种模式下用这些规则给生成的代码把关并最终通过交付前自检清单。一、这份文档在仓库中的角色naming-and-functions.md位于技能目录plugins/agentic-awesome-skills-claude/skills/clean-code-guard/references/下是该技能六份参考文档之一另有 comments-and-formatting.md、solid.md、dry-kiss-yagni.md、ai-failure-modes.md、review-checklist.md。从 SKILL.md 的 frontmatter 可以看到这个技能的定位是name:clean-code-guarddescription: Review generated or changed production code with Clean Code, SOLID, DRY, KISS, YAGNI, and LLM-specific failure-mode checks.risk:critical技能本身是一个可移植的指令型技能portable instruction skill不需要 MCP 服务器、网络访问、API Key、shell 命令或本地可执行脚本任何支持SKILL.md加直接链接的references/文件的运行时都能使用。它不替代项目的 linter、格式化器、类型检查器或测试运行器——那些负责机械校验而本技能负责代码质量的判断层。三种使用模式Guard-pass 模式守卫检查推荐代码被生成、编辑、重构或修复之后对照硬性戒律检查 diff 或目标文件在呈现、提交或合并之前修复违规。Live 模式实时书写用户在做高风险代码编辑前显式调用书写过程中应用同一套戒律交付前跑自检清单。Review 模式审查模式用户要求审查、审计、评判或评分代码时按 review-checklist.md 走查目标文件并产出结构化发现报告未经要求不修改代码。本指南聚焦其中与命名和函数直接相关的规则体系——也就是下面要讲的 N1–N6 与 F1–F10。二、有意义的命名六条戒律N1–N6命名的核心原则一句话一个名字应该告诉你它为什么存在、它做什么、它如何被使用。如果需要一个注释来解释某个名字那这个名字就是错的。N1. 意图自明Intention-revealing名字必须直接揭示意图而不是描述类型或位置。以下写法全部不合格d // elapsed time in days —— 需要注释解释名字不合格 ts [] // 无法判断是 timestamps 还是别的什么 fn(xs) // 函数名不表达任何行为参数也不表达含义合格写法elapsedDays timestamps filterOverdueInvoices(invoices)从 SKILL.md 的硬性戒律第 1 条可以印证这条规则在技能中的强制地位Names reveal intent.… A name must answerwhy it exists and what it does.名字必须回答它为什么存在、做什么。N2. 不传播错误信息、不使用编码No disinformation, no encodings禁止匈牙利命名法strName、iCount、接口前缀IIUserService、成员前缀m_。同时除非类型真的是 list否则不要加 List 后缀——accountList实际存的是set这就是传播错误信息disinformation。Bad:strFirstName、IUserRepo、m_count、userArray当它不是数组时Good:first_name、UserRepo、count、users_by_idN3. 有意义的区分Meaningful distinctions不要用噪音词来区分名字。ProductInfo、ProductData、Product三者区别是什么getActiveAccount与getActiveAccountInfo又有什么不同如果区分是真实的那就命名这个区分本身例如getActiveAccountById与getActiveAccountByEmail。N4. 可搜索、可发音Searchable, pronounceable单字母名字只在短循环作用域内可接受如for i in range(...)其他任何地方都会伤害 grep。MAX_RETRIES是可搜索的而裸数字7不是。如果名字在代码评审中无法读出声它就是坏名字。书中经典反例genymdhms——正解是generation_timestamp。N5. 类名是名词方法名是动词User、Invoice、Account——类是事物saveInvoice、computeTotal、notifyUser——方法是动作。命名为ProcessInvoice的类和命名为Invoice的方法都是错误的。N6. 禁用通用名Banned generic names没有限定词时以下名字永远违反意图自明原则data、data2、data_finalresult、result_finalitem、value、temp、obj、infohelper、manager、utils、commonhandle_*、process_*、do_*当*本身也很通用时带限定词的版本则是合格的raw_csv_bytes、parsed_invoice、dedup_by_email。限定词把通用名词变成了能回答它代表什么的自明名字。这一禁令在 SKILL.md 的硬性戒律第 1 条中被原样复述并延续到了 review-checklist.md Section A 的审查第一步Scan all identifiers. Flag generic ones:data,result,item,temp,value,obj,info,helper,manager,utils,handle_*,process_*,do_*without qualifier.三、函数十条戒律F1–F10F1. 小。然后更小。目标函数不超过 20 行。Uncle Bob 更严格的版本是 2–4 行。如果一个函数在一屏内放不下说明它做了太多事——提取。SKILL.md 的硬性戒律第 2 条将≤20 行、单一抽象层级、只做一件事固定为强制项并在自检清单中要求对新函数计数行数 ≤ 20参数 ≤ 4复杂度感觉 ≤ 10名字是否揭示意图F2. 只做一件事Do one thing判断标准当你无法从该函数中提取出另一个、且名字不是对函数体重述的函数时它才只做一件事。如果compute_invoice里有一段 10 行、可以合理命名为apply_discount的代码块那么原函数就在做多件事。F3. 每个函数一个抽象层级One level of abstraction per function混用抽象层级是最常见的隐蔽缺陷。不要把 HTTP 调用、SQL 查询、正则解析和业务规则放进同一个函数——那是四个层级。Bad混了四个层级连接、查询、格式化、展示renderUserReport(userId): connection openDatabaseConnection() row queryUserRow(connection, userId) displayName row.firstName row.lastName markup h1 displayName /h1 return markupGood每层一个函数逐级下沉renderUserReport(userId): user userRepository.findById(userId) return userReportView.render(user)F4. 步降规则Step-down rule文件应能自上而下阅读每个函数之后紧跟抽象层级低一级的函数调用方在 Callee 之上。这正是 comments-and-formatting.md 中 Fmt3 Caller above callee 所引用的同名规则两份参考文档互相呼应。F5. 少参数Few arguments零个最好一个可以两个尚可。三个应当避免四个或更多需要非常特殊的理由——通常意味着应该传入配置对象。到五个参数时立即停下来提取 request/config 对象record、struct、DTO 或等价物。在 SKILL.md 中这条被收紧为硬性戒律第 3 条Four arguments is the hard ceiling.At five, stop and introduce a request/config object (record, struct, DTO, or equivalent).四个参数是硬上限。review-checklist.md 的 Section A 也要求逐一检查每个函数lines ≤ 20? params ≤ 4? one thing? one level of abstraction?F6. 无标志参数No flag arguments切换行为的布尔参数永远是错的——拆成两个函数。Bad:render(invoice, asHtml): if asHtml: ... else: ...Good:renderInvoiceHtml(invoice) renderInvoicePdf(invoice)同理适用于modex这类字符串枚举——当 mode 改变的是行为时。区分标准很关键如果mode参数化的是数据locale、currency那是合理的如果它参数化的是执行哪个函数请拆分。F7. 无输出参数 / 命令查询分离Command-Query Separation一个函数要么返回值查询要么有副作用命令二者不可兼得CQS由 Fowler 提出来源见 sources.md 中的 CommandQuerySeparation 条目。Badbool 含义不明是保存成功还是记录存在调用方无法判断save(record) - boolean // Returns true if saved, false if record was not found.Good命令与查询彻底分离save(record) recordExists(recordId) - booleanSKILL.md 的硬性戒律第 4 条将其固定为No output arguments. A function either returns a value (query) or has a side effect (command). Never both. Command names use verbs; query names use nouns or getter-style names.F8. 查询函数无副作用No side effects in queriesgetter 风格、finder 风格或谓词风格的函数绝不能修改状态。如果它确实需要缓存把缓存写入记录在 debug 级别日志即可不得改变可观察行为。F9. 优先异常而非返回码Prefer exceptions to return codesif save(x):是代码坏味。要么 save 成功不返回任何值要么它抛出异常如InvoiceSaveError。返回码会在调用栈中层层传播然后被遗忘异常则无法被静默忽略。F10. 重复是万恶之源Duplication is the root evil如果两个函数共享一段非平凡代码块提取它。但——这条有一个重要的例外参见 dry-kiss-yagni.md即 Sandi Metz 的错误抽象比重复更糟糕wrong abstraction告诫。这份交叉引用值得展开DRY 的准确定义来自 Hunt Thomas 的《程序员修炼之道》——系统中的每一条知识都必须有单一、无歧义、权威的表示。它针对的是知识knowledge的重复而非文本text的重复两个看起来相似但编码了不同规则不同知识的函数并不违反 DRY而同一条规则同时写在代码、数据库 schema 和文档里才是违反。因此 F10 的提取动作之前必须回答这段重复背后能否命名出真正的共享知识命名不出来就保留重复——这是 dry-kiss-yagni.md 给出的铁律Do not introduce an abstraction to eliminate three lines of duplication unless you can name the underlyingknowledgethe lines represent.四、审查模式下的落地Section A 走查流程命名与函数规则在 Review 模式中并非零散应用而是被组织成 review-checklist.md 的Section A — naming and functions固定走查流程扫描所有标识符标记无限定词的通用名data、result、item、temp、value、obj、info、helper、manager、utils、handle_*、process_*、do_*。对每个函数行数 ≤ 20参数 ≤ 4只做一件事单一抽象层级违规即标记。标记布尔标志参数。标记既返回值又模糊地修改可观察状态的函数CQS 违规。标记会修改状态的 getter 风格或谓词风格函数。审查产出遵循固定模板发现按严重度分级Critical安全、正确性、数据丢失、吞异常、硬编码成功返回、Important设计缺陷SOLID 违规、过早抽象、参数爆炸、通用命名、Nit风格、循环外的单字母名、公共 API 缺少契约文档。每条发现必须引用违规代码文件 行号、命名所违反的原则或 AI 失败模式、给出修复方案并给出严重度——没有引用就没有发现没有修复就没有发现。五、交付前自检清单命名与函数专项原文档在结尾给出了交付前必须逐条通过的专项自检与 SKILL.md 的全局自检走查戒律 1–24配套使用。发布代码前逐条回答所有名字能否不需要注释就回答它代表什么函数是否都 ≤ 20 行函数是否只做一件事能否提取出名字不重述函数体的另一个函数若能就是在做多件事。是否消除了混用抽象层级是否存在参数超过 4 个的函数提取配置对象。是否存在布尔标志参数拆分。是否存在既返回值、又以调用方依赖的方式修改状态的函数拆分。全局层面SKILL.md 还要求守卫通过后向用户汇报格式为逐条file[:line] — what changed并以一行收尾clean-code-guard: N fixed, M flagged for author或clean-code-guard: clean。注意只报告实际做出的修改绝不可估算质量分数或百分比——因为没有基线存在任何数字都是编造的。六、规则被质疑时怎么办当用户对某条规则提出异议时技能的处理方式见 SKILL.md是引用相关references/文件中的来源名称Uncle Bob、Fowler、Hunt Thomas、McCabe、Metz 等一手来源以及 2024–2026 年已发表的 LLM 代码生成研究需要 URL 时才查阅 sources.md 的集中书目。如果用户有上下文相关的正当理由需要覆盖规则例如一个配置 DTO 的构造函数确实需要 8 个参数则把例外记录成代码注释注明被覆盖的原则、原因和复查触发条件revisit trigger。没有复查触发条件的例外注释本身就会成为下一次审查的发现——没有退出机制的权衡只是拖延的债务。延伸阅读naming-and-functions.md — 本文主体原文命名与函数规则全集SKILL.md — 技能入口三种模式、24 条硬性戒律与全局自检dry-kiss-yagni.md — F10 的例外DRY/KISS/YAGNI 与错误抽象告诫comments-and-formatting.md — 第 4、5 章注释纪律与排版含步降规则的呼应solid.md — 五大原则的现代表述与检测坏味review-checklist.md — Review 模式的完整走查流程与发现报告模板sources.md — 集中书目经典文献与 LLM 代码生成研究赞分享AI 技能AI 插件【免费下载链接】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 中的 SOLID 五原则clean-code-guard 参考文档深度解读Agentic Awesome Skills 中的 SOLID 五原则clean code guard 参考文档深度解读 导读 SOLID 是面向对象设计中最AI 技能AI 插件Agentic Awesome Skills 架构模式实战Clean Architecture、Hexagonal 与 DDD 实施手册Agentic Awesome Skills 架构模式实战Clean Architecture、Hexagonal 与 DDD 实施手册 本手册以 agentAI 技能AI 插件agentic-awesome-skills 中的 Karpathy 指南为 LLM 编码行为设定四条纪律性护栏agentic awesome skills 中的 Karpathy 指南为 LLM 编码行为设定四条纪律性护栏 本文以 agentic awesome skAI 技能AI 插件上一篇GPT Image 2提示词库 awesome-gpt-image-2 完全指南16000精选AI绘图Prompt一次看懂下一篇终极指南用虎符台彻底解决全面战争MOD管理难题打造完美游戏体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考