clean-abap

Clean ABAP

このスキルは、ABAP の成果物に関するタスクでは必ず使用してください。特に、グローバルクラス、ローカルクラス、インターフェース、レポート、インクルード、関数モジュール、メソッド、内部テーブル、例外処理、ABAP Unit テストが対象です。

使用する場面

• 新しい ABAP コードを作成するとき。
• レガシー 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 にします。

メソッド

• メソッドは一つのことだけを行うようにします。
• メソッドは小さく、目的を絞ったものにします。
• メソッド内のすべてのステートメントで、抽象度をそろえます。
• 静的メソッドが明らかに適切な場合を除き、インスタンスメソッドを優先します。
• パブリックなインスタンスメソッドは、通常インターフェースを通じて公開します。
• インポートパラメーターの数は少なくします。
• 関係のない任意パラメーターを追加する代わりに、メソッドを分割します。
• ブール型の入力パラメーターによって二つの動作が生じる場合は、その使用を避けてください。代わりにメソッドを分割します。
• 論理的な結果を一つ返します。
• 単一の結果を返すメソッドでは、EXPORTING より RETURNING を優先します。
• 強い理由がない限り、RETURNING、EXPORTING、CHANGING を混在させないでください。
• CHANGING は必要最小限に使用します。
• より具体的な名前のほうが明確な場合を除き、RETURNING パラメーター名には RESULT を優先します。
• 無効な入力は速やかに失敗させます。
• 可能な場合は、正常系のロジックとエラー処理のロジックを分離します。

変数、テーブル、文字列、条件

• インライン宣言は、最初に使用する箇所の近くで行います。
• 概念上必要なブロックの外に変数が漏れないようにします。
• 宣言が意味のあるグループを形成する場合を除き、先行する宣言を連ねるのは避けます。
• 使用方法に応じて、STANDARD、SORTED、HASHED のいずれかを意図的に選択します。
• DEFAULT KEY は避け、明示的なキーまたは EMPTY KEY を使用します。
• 配列としての意味が意図されている場合を除き、APPEND TO より INSERT INTO TABLE を優先します。
• 明瞭さが向上する場合は、冗長な READ TABLE ... sy-subrc パターンより LINE_EXISTS、テーブル式、直接読み取りを優先します。
• テキストの組み立てには文字列テンプレート |...| を使用します。
• ブール論理では、ABAP_BOOL、ABAP_TRUE、ABAP_FALSE、XSDBOOL を一貫して使用します。
• 肯定条件を優先します。
• 可読性が向上する場合は、NOT ... IS より IS NOT 形式を優先します。
• 複雑な条件は、ヘルパー変数またはヘルパーメソッドに切り出します。

エラー処理

• 戻りコードより例外を優先します。
• クラスベースの例外を使用します。
• 可能な限り、操作ごとに意味のある例外スーパタイプを1つスローします。
• 外部の例外型が独自の抽象化を通じて漏れないよう、ラップします。
• 想定される回復可能な失敗には CX_STATIC_CHECK を使用します。
• 通常は回復不可能な状況に限り、CX_NO_CHECK を使用します。
• 真に回復不可能なプログラミングエラーまたはランタイムエラーの場合に限り、ダンプを発生させます。
• 使用可能な場合は、RAISE EXCEPTION NEW を優先します。

コメントと書式

• コメントを追加する前に、コードで意図を表現します。
• コメントでは、何をしているかではなく、なぜそうするのかを説明します。
• 不要になったコードはコメントアウトせず、削除します。
• 手動のバージョン管理コメントは避けます。
• TODO、FIXME、XXX は控えめに使用し、特定可能な担当者を記載します。
• オブジェクトまたはチームで既に採用されている書式スタイルに一貫して従います。
• 入力速度ではなく、読みやすさを重視して書式を整えます。
• 1行につき1つのステートメントにします。
• ネストは浅く保ちます。

テスト

• テストで依存関係を置き換えられるようにコードを記述します。
• プライベートな内部実装ではなく、公開された動作をテストします。
• テストは読みやすく、目的を明確にします。
• 適切な場合はローカルテストクラスを使用します。
• テスト対象のコードとテストメソッドには、意味のある名前を付けます。
• 可読性の向上に役立つ場合は、given-when-then 構成に従います。
• アサーションは対象を絞り、具体的にします。

ABAP レビューチェックリスト

ABAP コードをレビューまたは生成するときは、次の点を明示的に確認します。

• 名前は内容を適切に表し、一貫していますか？
• 対象リリースでサポートされるモダンな構文を使用していますか？
• 不要なネストや分岐はありませんか？
• 各メソッドの責務は明確に1つですか？
• パラメーターは最小限で、意味が明確ですか？
• 例外処理は明示的で、一貫していますか？
• 内部テーブルは適切な型が指定され、意図に沿ってアクセスされていますか？
• コメントは、コードの不備を補うものではなく、役に立つものですか？
• コードはテスト可能で、テストは動作に焦点を絞っていますか？

レガシーコードのルール

• 全体を書き直すのではなく、段階的にコードを改善します。
• ボーイスカウトルールに従い、コードを見つけたときより少しきれいな状態にします。
• 広範なリファクタリングにリスクがある場合は、小さく整理された領域を作ります。
• 大きなオブジェクトが一貫してレガシースタイルで書かれている場合、タスクが特にリファクタリングを目的としていない限り、一部分だけを中途半端にモダン化するのは避けます。
• モダン化する際は、変更範囲を広げることより、可読性、安全性、テスト可能性を優先します。

出力に関する期待事項

このスキルを適用するとき、エージェントは次のようにします。

• ABAP 固有のトレードオフを、簡潔かつ具体的に説明します。
• Clean ABAP スタイルに沿ったコード例を優先します。
• 構文が新しい ABAP プラットフォームに依存する場合は、リリースに関する前提を明記します。
• より整理された代替案ではなく、レガシーコードとの一貫性を意図的に保つ場合は、その旨を伝えます。

ソース

このスキルは、このリポジトリの CleanABAP.md ソースドキュメントで管理されている Clean ABAP のガイダンスに基づいています。