SuperAPI AI 工具集

clean-code

编程与开发

查看项目

更新于 10-15 16:27

技能介绍

该技能收录 Robert C. Martin(Uncle Bob)的 Clean Code 最佳实践,是一份综合性的软件工艺指南,基于其《Clean Code:敏捷软件开发实践指南》一书,并在原 2008 年建议已被取代之处加入了现代修正。技能包含 48 条规则,分布在 10 个类别中,按影响程度赋予优先级,用以指导代码评审、重构决策与新的开发工作。示例以 Java 为主,但所述原则与语言无关。

适用时机

在以下情况下参考这些准则:编写新的函数、类或模块;为变量、函数、类或文件命名;评审代码中的可维护性问题;重构既有代码以提升清晰度;编写或改进单元测试;封装第三方依赖。

规则类别与优先级

优先级从高到低依次为:第 1 类“有意义的命名”(CRITICAL,前缀 name-);第 2 类“函数”(CRITICAL,前缀 func-);第 3 类“注释”(HIGH,前缀 cmt-);第 4 类“格式”(HIGH,前缀 fmt-);第 5 类“错误处理”(HIGH,前缀 err-);第 6 类“对象与数据结构”(MEDIUM-HIGH,前缀 obj-);第 7 类“边界”(MEDIUM-HIGH,前缀 bound-);第 8 类“类与系统”(MEDIUM-HIGH,前缀 class-);第 9 类“单元测试”(MEDIUM,前缀 test-);第 10 类“浮现式与简单设计”(MEDIUM,前缀 emerge-)。

规则速查

  1. 有意义的命名(CRITICAL):name-intention-revealing(使用揭示意图的名称);name-avoid-disinformation(避免误导性名称);name-meaningful-distinctions(做出有意义的区分);name-pronounceable(使用可发音的名称);name-searchable(使用可搜索的名称);name-avoid-encodings(避免名称中的编码);name-class-noun(类名使用名词短语);name-method-verb(方法名使用动词短语)。

  2. 函数(CRITICAL):func-small(保持函数短小);func-one-thing(函数只做一件事);func-abstraction-level(保持同一抽象层级);func-minimize-arguments(尽量减少函数参数);func-no-side-effects(避免副作用);func-command-query-separation(分离命令与查询);func-dry(不要重复自己)。

  3. 注释(HIGH):cmt-express-in-code(用代码而非注释表达);cmt-explain-intent(用注释解释意图);cmt-avoid-redundant(避免冗余注释);cmt-avoid-commented-out-code(删除被注释掉的代码);cmt-warning-consequences(对后果使用警告性注释)。

  4. 格式(HIGH):fmt-vertical-formatting(使用垂直格式提升可读性);fmt-horizontal-alignment(避免水平对齐);fmt-team-rules(遵循团队格式规则);fmt-indentation(遵守缩进规则)。

  5. 错误处理(HIGH):err-use-exceptions(将错误处理与正常路径分离);err-write-try-catch-first(先写 try-catch-finally);err-provide-context(在异常中提供上下文);err-define-by-caller-needs(按调用方需求定义异常);err-avoid-null(避免返回和传递 null)。

  6. 对象与数据结构(MEDIUM-HIGH):obj-data-abstraction(将数据隐藏在抽象之后);obj-data-object-asymmetry(理解数据与对象的反对称性);obj-law-of-demeter(遵循迪米特法则);obj-avoid-hybrids(避免数据与对象混合结构);obj-dto(使用 DTO 进行数据传输)。

  7. 边界(MEDIUM-HIGH):bound-wrap-third-party(封装第三方 API);bound-learning-tests(为第三方代码编写学习测试)。

  8. 类与系统(MEDIUM-HIGH):class-small(保持类小);class-cohesion(维持类内聚);class-organize-for-change(为变更组织类);class-isolate-from-change(将类与变更隔离);class-separate-concerns(分离构造与使用)。

  9. 单元测试(MEDIUM):test-first-law(遵循 TDD 三定律);test-keep-clean(保持测试整洁);test-one-assert(每个测试一个概念);test-first-principles(遵循 FIRST 原则);test-build-operate-check(使用 Build-Operate-Check 模式)。

  10. 浮现式与简单设计(MEDIUM):emerge-simple-design(遵循简单设计四原则);emerge-expressiveness(最大化表达力)。

使用方法

阅读各参考文件以获取详细说明和代码示例:章节定义(类别结构与影响等级)、规则模板(新增规则的模板)。

参考文件

references/_sections.md:类别定义与排序;assets/templates/_template.md:新增规则的模板;metadata.json:版本与参考信息。

目前资料中未提供安装命令、价格、平台限制或具体使用步骤等信息。