document-code

コードのドキュメント化

動作、構造、公開契約を変更せずに、コードの理解しやすさを高めます。意図、不変条件、見落としやすいトレードオフを説明するのに必要な範囲でのみ、ドキュメントを追加します。明確なコードを言い換えるだけの記述は避けてください。

対象範囲

• ユーザーがコードを選択またはタグ付けしている場合は、そのコードを使用します。
• ユーザーが対象を指定した場合は、指定されたファイル、ディレクトリ、シンボル、説明を使用します。
• 対象を指定せず、全般的なドキュメント化を求められた場合は、まずステージ済みのソースコードの変更を確認します。ステージ済みの変更がない場合は、ステージされていないソースコードの変更を確認します。
• 編集対象は、ターゲットまたは差分に含まれる言語のソースコードファイルに限定します。拡張子、プロジェクトの構成、インポート、ビルド設定からソースファイルを判断してください。拡張子の一覧は網羅的ではありません。
• ユーザーから明示的に編集を求められない限り、ドキュメント、JSON、YAML、ロックファイル、生成ファイル、画像など、コード以外のファイルは除外します。
• フィルタリング後にソースコードファイルが残らない場合は、ドキュメント化する対象がないことを伝え、変更を加えないでください。

厳守事項

• 実行時の動作を編集しないでください。
• シンボルの名前変更、ロジックの並べ替え、簡略化、ヘルパーの抽出、ファイルの再構成、書式の変更をしないでください。
• API、型、シリアライズされたデータ、ユーザーに表示されるテキスト、エラー、スナップショット、アナリティクスイベント、アクセシビリティのセマンティクス、タイミング、順序、永続化を変更しないでください。
• 次の形式のドキュメントのみ追加または改善してください。
  • インラインコメント
  • docstring、doc comment、JSDoc、rustdoc、Go の doc comment、XML docs など、言語に適した API ドキュメントや、プロジェクトで同等に定着している形式
  • ステップ 5 の条件を満たす、対象を絞ったドキュメントファイル
• コードを理解するのに簡略化、名前変更、リファクタリングが必要な場合、このワークフローでは修正しないでください。その制約を報告してください。

ワークフロー

1. 対象を特定します。

   • 明示的に選択された項目やタグ付けされたファイルを、広範な差分より優先します。
   • 近くにドキュメントを追加できそうなコードがあっても、無関係なファイルは避けてください。

2. 周辺の文脈を十分に確認します。

   • 意図を説明するうえで役立つ場合は、呼び出し元、公開 API、テスト、型、周辺のコメント、既存のドキュメント、ローカルの慣例に加えて、コミットや PR の履歴も確認します。意図が記録されているのは、こうした履歴だけということもよくあります。
   • ドキュメントを書く前に動作を理解します。入力、出力、副作用、エラー経路、ライフサイクルの順序、リトライ、冪等性、並行性、永続化、ビジネスルールを確認してください。
   • 対象の動作と、見落としやすい各要素の背景にある理由を説明できるまで確認します。
   • 十分に確認しても意図が不明な場合は、理由を推測せず、その旨を伝えてください。現在は納得できるコードでも、かつての理由が今も当てはまるとは限らず、後から推測した理由をコメントに書けば、誤ったドキュメントになってしまいます。
   • 新しい用語を作るのではなく、プロジェクトで定着している用語を優先します。

3. 理解に役立つことだけを文書化します。

   • 一見して分からない不変条件、前提条件、事前条件、所有権のルールに加え、その背景にあるトレードオフ、却下した代替案、互換性や移行上の制約を文書化します。
   • 意図的な意外性と偶発的なものを区別します。外部依存関係、プラットフォーム、プロトコルによって強制される動作や、制約やトレードオフなどの理由があって選択された動作にはコメントを付けます。理由のない分かりにくい構造はリファクタリングの対象です。コメントで取り繕わず、Needs refactor, but not changed に記載します。
   • 並行処理、順序、クリーンアップ、再試行、バックオフ、冪等性に関する想定に加え、誤解されやすいフォールバック、障害時の動作、境界での動作を明確にします。
   • 構文だけでは分からないビジネスルールやドメインルールを記録します。
   • 読者がそのヘルパーの存在理由を疑問に思うのが妥当な場合は、プライベートヘルパーの意図を説明します。
   • パラメーターの意味、戻り値の仕様、副作用、エラー、不変条件、ドメインルール、ライフサイクル上の責務がシグネチャから明らかでない場合は、公開 API、エクスポートされた API、複雑なプライベートヘルパーに、言語に適した API ドキュメントを使用します。
   • 単純なプライベート関数は、分かりやすい名前とシグネチャに任せます。明白なコードに必須のドックストリングを付けると、ノイズや古くなったドキュメントの原因になります。

4. 分かりやすいコードには手を加えません。

   • 有能な読者が「なぜ？」と立ち止まって考える場合にのみコメントを追加します。その疑問を具体的に言えない場合は、コードにコメントを付けません。
   • コメントは意図と安定した動作に結び付け、実装の詳細が変わっても正確さを保てるようにします。
   • 個々のエッジケースにそれぞれコメントが必要になる場合は、コメントを列挙する代わりに、サマリーでテストを推奨します。同様に、「変更してはならない」不変条件については、それを文書化し、サマリーで最も低コストで強制できるチェック（型、テスト、リンター）を推奨します。文章だけでは強制できません。

5. 適切な場所にドキュメントを記述します。

   • 原則として、該当箇所のコメントを使用します。単一の分岐、ヘルパー、呼び出し箇所のそばで理由を説明できる場合は、そこで説明します。
   • 不変条件は、それを所有する境界で一度だけ明記し、すべての利用箇所で繰り返さないようにします。読者が一度で把握でき、記述の食い違いも防げます。
   • ドキュメントファイルを選ぶのは、次の条件をすべて満たす場合に限ります。理由を理解するのに2つ以上のファイルまたはモジュールが関わること、単一の箇所のそばに置くと文脈が失われること、インラインで記述すると同じ説明を複数箇所で繰り返すことになることです。判断に迷う場合は、該当箇所に記述します。
   • 信頼できる情報源は1つにします。理由の全容はドキュメントファイルに記述し、近くの読者が参照先とその場で必要な理由を知る必要がある箇所に限り、短いコメントでそのファイルを示します。
   • 対象を絞ったドキュメントファイルでは、モジュール間の構造、ライフサイクル、順序を文章より視覚的に把握しやすい場合、図（シーケンス図、状態図、フロー図）を使用します。リポジトリに既存の図の規約があればそれに従い、なければ Markdown ファイルでは mermaid を標準とします。文章で説明できる内容を図にせず、実装の詳細ではなく、安定した動作を図にします。
   • 可能であれば、関連する既存ドキュメントの近くに新しいドキュメントを配置し、対象を絞った内容にします。

6. プロジェクト内のスタイルに合わせます。

   • リポジトリのコメントスタイル、言語ごとのドキュメント規約、大文字・小文字の使い分け、句読点、用語に従います。
   • コメントは説明対象のコードの近くに置きます。
   • 公開 API や複数段階にわたる不変条件に構造が必要な場合を除き、ブロックコメントより簡潔なコメントを優先します。
   • 有用な既存コメントは維持し、古くなったコメントや誤解を招くコメントは、対象箇所の範囲内でのみ更新します。変更箇所にある既存のコメントとドックストリングを確認し、実装、動作、制約、公開契約に合わなくなったものを修正します。

7. 結果を検証します。

   • 差分を読み直し、変更されたのがコメント、ドキュメント文字列、または明示的に必要なドキュメントだけであることを確認します。
   • 実行可能なコード、書式のみの構造、生成ファイル、無関係なファイルに変更が加えられていないことを確認します。
   • 追加したコメントがすべて、意図、根拠、制約、または自明でない動作を説明していることを確認します。
   • コメントやドキュメント文字列がツールに影響する可能性がある場合は、利用可能な範囲で最も対象を絞った検証（リンターやドキュメントのチェックなど）を実行します。
   • コメントのみの変更でチェックが利用できない、または不要な場合は、その旨を伝えます。

出力

変更内容に見合った簡潔な要約を返します。小規模な作業では、ドキュメントに何を記載したか、検証を実行したかどうかを含め、短い段落または具体的な箇条書き2～4項目にまとめます。

大規模なドキュメントの更新では、有用な情報を加えるセクションだけを含めます。

• 記録した内容：コードだけでは分からなかったこと、つまり不変条件、トレードオフ、制約について、コメントが追加されたファイルの一覧ではなく、該当するシンボルまたはドキュメントの場所を示します。
• リファクタリングが必要だが未対応：単純化、命名、構造の見直しが本当の解決策となる、不明瞭な箇所を列挙します。
• 検証：実行したコマンドと結果を列挙するか、実行しなかった理由を述べます。
• 範囲：レビューしたファイルを1行で示します。

動作が変わった、バグを修正した、またはコードを単純化したと主張しないでください。目的は、動作を変えずに理解しやすくすることです。