clean-abap

Clean ABAP

只要任务涉及 ABAP 构件，尤其是全局类、本地类、接口、报表、包含程序、函数模块、方法、内表、异常处理或 ABAP Unit 测试，就使用此技能。

使用场景

• 编写新的 ABAP 代码。
• 重构旧版 ABAP 代码。
• 审查 ABAP 代码的可读性、可维护性或一致性。
• 为 ABAP 中的类、方法、参数、变量、常量或测试代码命名。
• 在旧式与现代 ABAP 语法之间做出选择。
• 改进 ABAP 的错误处理、格式和单元测试。

工作原则

1. 首先保持行为不变。 只有用户明确要求时，才更改外部行为。

2. 选择最适合代码库和发行版本的简洁方案。 如果目标系统支持，就使用现代、面向对象且表达力强的 ABAP。

3. 没有理由时，不要混用相互冲突的风格。 如果旧版对象始终采用旧式风格，且任务不包括全面清理，就避免只改写部分代码，以免对象内部风格不一致。

4. 优先考虑可读性，而不是炫技。 优先选择便于浏览、解释、测试和安全修改的代码。

5. 不要过早优化。 只有在有测量结果、已知热点路径或明确的项目约束作为依据时，才将性能问题视为真实问题。

核心指南

命名

• 使用能表达意图的描述性名称。
• 优先使用其他开发者熟悉的问题领域或解决方案领域术语。
• 始终一致地使用 snake_case。
• 避免不必要的缩写。如果必须使用缩写，请始终使用同一种写法。
• 类、接口和对象使用名词命名。
• 方法和函数使用动词或动词短语命名。
• 除非 data、info 或 object 等冗余词确实能表达含义，否则不要使用。
• 除非现有代码库明确统一采用匈牙利命名法或 iv_、ev_、rv_、lt_、ls_ 等编码前缀，且任务要求保持一致，否则不要使用这些写法。
• 不要用 lines、line_exists、condense 或 strlen 等方法名遮蔽 ABAP 内置函数。

语言与结构

• 可行时优先采用面向对象编程，而不是过程式编程。
• 如果能提升清晰度，优先使用函数式、表达式导向的 ABAP，而不是冗长的过程式语句。
• 支持的发行版本提供现代替代方案时，避免使用过时的语言结构。
• 只有在设计模式能明显改善设计时才使用。
• 除非继承确实是恰当的模型，否则优先采用组合而非继承。
• 除非类明确用于继承，否则将类声明为 FINAL。
• 默认将成员设为 PRIVATE。

方法

• 每个方法只做一件事。
• 保持方法小巧、专注。
• 方法中的所有语句应处于同一抽象层次。
• 除非静态语义明显更合适，否则优先使用实例方法。
• 公共实例方法通常应通过接口公开。
• 尽量减少导入参数的数量。
• 应拆分方法，而不是添加无关的可选参数。
• 如果布尔输入参数会导致两种行为，就避免使用；改为拆分方法。
• 返回一个逻辑结果。
• 对于只返回一个结果的方法，优先使用 RETURNING，而不是 EXPORTING。
• 除非有充分理由，否则不要混用 RETURNING、EXPORTING 和 CHANGING。
• 谨慎使用 CHANGING。
• 除非更具体的名称确实更清晰，否则将 RESULT 作为 RETURNING 参数名。
• 对无效输入快速失败。
• 尽可能将正常路径逻辑与错误处理逻辑分开。

变量、内表、字符串和条件

• 优先在首次使用附近进行内联声明。
• 不要让变量超出其概念上所需的代码块范围。
• 避免预先连续声明多个变量，除非这些声明构成一个有意义的整体。
• 根据用途有意识地选择内表类型：STANDARD、SORTED 或 HASHED。
• 避免使用 DEFAULT KEY；优先使用显式键或 EMPTY KEY。
• 除非有意采用数组语义，否则优先使用 INSERT INTO TABLE 而不是 APPEND TO。
• 在有助于提高可读性的情况下，优先使用 LINE_EXISTS、内表表达式和直接读取，而不是冗长的 READ TABLE ... sy-subrc 模式。
• 使用字符串模板 |...| 来拼接文本。
• 在布尔逻辑中一致地使用 ABAP_BOOL、ABAP_TRUE、ABAP_FALSE 和 XSDBOOL。
• 优先使用肯定条件。
• 在有助于提高可读性的情况下，优先使用 IS NOT 形式，而不是 NOT ... IS。
• 将复杂条件提取为辅助变量或辅助方法。

错误处理

• 优先使用异常而不是返回代码。
• 使用基于类的异常。
• 尽可能为每个操作抛出一个有意义的异常超类型。
• 包装外部异常，而不要让外部异常类型泄漏到自己的抽象中。
• 对预期且可恢复的失败使用 CX_STATIC_CHECK。
• 仅在通常不可恢复的情况下使用 CX_NO_CHECK。
• 仅对真正不可恢复的编程或运行时故障触发转储。
• 在可用时，优先使用 RAISE EXCEPTION NEW。

注释和格式

• 先通过代码表达意图，再添加注释。
• 用注释解释原因，而不是描述代码做了什么。
• 删除无效代码，不要将其注释掉。
• 避免手动编写版本注释。
• 谨慎使用 TODO、FIXME 或 XXX，并注明可识别的负责人。
• 遵循对象或团队现有的格式风格，保持一致。
• 优化格式以便阅读，而不是为了提高输入速度。
• 每行只写一条语句。
• 尽量减少嵌套层级。

测试

• 编写代码时应确保依赖项可在测试中替换。
• 测试公开行为，而不是私有实现细节。
• 让测试易于阅读且目标明确。
• 适当时优先使用本地测试类。
• 为被测代码和测试方法使用有意义的名称。
• 有助于提高可读性时，遵循 given-when-then 结构。
• 让断言聚焦且具体。

ABAP 评审清单

评审或生成 ABAP 代码时，请明确检查以下问题：

• 名称是否具有描述性且保持一致？
• 代码是否使用了目标发行版支持的现代语法？
• 是否存在不必要的嵌套或分支？
• 每个方法是否只有一个明确的职责？
• 参数是否精简且有意义？
• 异常处理是否明确且一致？
• 内表是否进行了类型定义，并且访问方式是否经过审慎选择？
• 注释是否确有帮助，而不是在弥补代码质量不足？
• 代码是否便于测试，且测试是否聚焦于行为？

遗留代码规则

• 逐步改进代码，而不是强行全面重写。
• 遵循童子军规则：让代码比发现时稍微整洁一些。
• 如果大范围重构风险较高，就构建一些小而整洁的代码区域。
• 如果大型对象始终采用遗留风格，除非任务明确要求重构，否则不要只对其中一处进行半现代化改造。
• 进行现代化改造时，应优先考虑可读性、安全性和可测试性，而不是扩大改动范围。

输出要求

应用此技能时，Agent 应：

• 简要、具体地说明 ABAP 特有的权衡取舍。
• 优先提供符合 Clean ABAP 风格的代码示例。
• 当语法依赖较新版本的 ABAP 平台时，指出相关发行版假设。
• 说明何时是为了保持遗留代码的一致性而有意保留现状，没有采用更整洁的替代方案。

来源

此技能源自本仓库 CleanABAP.md 源文档中维护的 Clean ABAP 指南。