SuperAPI AI 工具集

clean-code

编程与开发

查看项目

更新于 10-16 09:28

技能介绍

用途:该技能以 Robert C. Martin(Uncle Bob)的《Clean Code》原则为核心,帮助把“能运行的代码”转化为“整洁的代码”。引用 Grady Booch 的观点:代码若能被原作者之外的开发者阅读并增强,才算整洁。

适用时机:编写新代码以保证高质量;审查 Pull Request 时给出基于原则的建设性反馈;重构遗留代码、识别并消除代码坏味道;改进团队标准,对齐业界最佳实践。

主要原则与能力:

  1. 有意义的命名:使用意图明确的名字(如 elapsedTimeInDays 而非 d);避免误导(是 Map 就不要叫 accountList);做出有意义的区分;避免不可发音或不可搜索的名字;类名用名词,方法名用动词。
  2. 函数:要短小,只做一件事,保持单一抽象层级,名字具描述性,参数越少越好(0 理想,1-2 尚可,3 个以上需强理由),避免副作用。
  3. 注释:不要为坏代码写注释,而应重写代码;好注释包括法律、信息性(正则意图)、澄清(外部库)、TODO;坏注释包括喃喃自语、冗余、误导、强制、噪音、位置标记。
  4. 格式化:采用报纸隐喻,高层次概念在上、细节在下;相关行保持靠近;变量在靠近使用处声明;重视缩进。
  5. 对象与数据结构:隐藏实现于接口之后;遵循迪米特法则,避免 a.getB().getC().doSomething();DTO 为仅有公共变量、无函数的类。
  6. 错误处理:用异常代替返回码;先写 try-catch-finally 以界定操作范围;不要返回 null,也不要传入 null。
  7. 单元测试:TDD 三法则(先有失败的测试再写生产代码,测试失败前不写更多测试,测试通过前不写更多生产代码);F.I.R.S.T. 原则:Fast、Independent、Repeatable、Self-Validating、Timely。
  8. 类:要小,遵循单一职责原则;遵循逐步下降规则,让代码像自上而下的叙述。
  9. 坏味道与启发式:僵硬、脆弱、不可移用、黏滞、不必要的复杂与重复。

实现检查清单:函数是否小于 20 行;是否只做一件事;命名是否可搜索且意图明确;是否通过让代码更清晰而避免了注释;是否传参过多;本次更改是否有失败的测试。

用法示例:用户可提出“重构这段可运行代码,让命名更清晰、单元更小、错误更显式,并保持行为不变,同时用聚焦测试验证”。

限制:仅在任务明确匹配上述范围时使用;输出不能替代特定环境的验证、测试或专家评审;若缺少必要输入、权限、安全边界或成功标准,应停下来请求澄清。