doc-comment-writer

Doc Comment Writer

将文档注释整理为持久且有价值的内容，帮助未来的メンテナー理解用途、契約、制約、そして実装から再構成しなくても分かる自明でない判断。名前、型、または単純な制御フローを言い換えるだけの説明は省略してください。

ワークフロー

1. 対象範囲とローカル規約を把握します。

   • ユーザーが指定した対象範囲に従います。言語で一般的なドキュメントコメントの形式と、ファイル内の既存のスタイルやコメントの密度を確認します。
   • 公開される動作や重要な不変条件を把握する必要がある場合に限り、近くにある型、テスト、呼び出し元、または類似ファイルを調べます。
   • 対象となるファイルとシンボル、および適用されるコメント構文とスタイルが明確になったら次に進みます。

2. 維持、変更、またはスキップを明確に判断します。

   • ファイル名やエクスポートから明らかでない責務、境界、使用パターンがある場合は、ファイルレベルのコメントを検討します。
   • 将来の読者が「これは何のためにあるのか？」または「何を維持しなければならないのか？」に答えるために内部ロジックを調べる必要がある場合は、コメントを追加します。
   • 既存のコメントは、削除すると読者にとって有益な情報が失われる場合に限り残します。古くなったコメントや分かりにくいコメントは修正し、宣言や実装を述べ直すだけのコメントは削除します。
   • 名前、シグネチャ、型、コンテキストからすでに答えが分かるシンボルには、ドキュメントを付けません。ファイルに新たなコメントが必要ない場合は、無理に編集せず、その旨を伝えます。
   • 対象範囲内のすべてのエクスポート済みまたは公開シンボルと既存のドキュメントコメント、および関連するファイルヘッダーについて、維持、追加、修正、削除、またはスキップの判断が明確になったら次に進みます。

3. 持続性のあるコメントを作成し、検証します。

   • 新規または修正するコメントすべてに、コメント規約の各ルールを適用します。
   • ドキュメントコメントでは説明しきれないローカルな不変条件や微妙な分岐の説明に限り、インラインコメントを使用します。
   • 最も範囲を絞った適切なフォーマッター、パーサー、リンター、ドキュメント、またはサンプルのチェックを実行します。利用できるものがない場合は、変更したコメント構文を確認し、その制約を報告します。
   • 変更したコメントがすべて規約を満たし、ローカルで有効な構文を使用し、関連する検証に合格するか、その制約が報告されたら完了です。

コメント規約

• 保証、副作用、失敗条件、ライフサイクルの想定、不変条件、境界、誤用のリスク、または長期的なトレードオフが重要な場合は、それらを説明します。
• ファイルレベルのコメントは短く、構造に関する内容にします。弱いコメントをいくつも書くより、内容のしっかりしたコメントを一つ書くことを優先します。
• 数値のしきい値、タイムアウト、上限、デフォルト値、定数値、メンバーの一覧、ファイル名、パスなど、変更されやすい事実の情報源はコード、型、設定です。説明文にリテラルや一覧を転記せず、意味上のルールを説明します。読者に必要な場合にのみ、担当するシンボル名を示します。説明されていないリテラルに名前が必要な場合は、説明で補うのではなく、コードの明確さに関する問題として報告します。
• 外部参照は例外として扱います。計画書、進捗ファイル、引き継ぎメモ、一時的な意思決定記録、課題やプルリクエストのスレッドなど、一時的または保守が不十分な資料は参照しないでください。長期的な理由はコメント自体に記載します。文書が権威ある、保守された仕様または契約であり、安定した場所にある場合に限り、その文書を参照します。
• 時期によって意味が変わる表現や、通常の変更ですぐ古くなる実装手順の説明は避けます。
• コードから推測した動作は慎重に表現します。実装が裏付けていない意図や保証を作り出してはいけません。
• リポジトリ内の情報から重要な理由を特定できない場合は、推測でコメントを書くのではなく、メンテナーへの具体的な質問として報告します。
• 汎用的な埋め草や言い換えを削除します。各コメントは、説明対象のシンボルの実装を見なくても役立つ内容にします。

対象の選び方

適切な対象には、ファイルやモジュールの境界、公開される保証や失敗時の動作、型の意味やライフサイクル、そして複雑な不変条件、プロトコル、正規化ルールを守る内部ヘルパーなどがあります。

ファイル名を繰り返すだけのファイルヘッダー、単純なアクセサーやラッパー、パラメーターや型の説明、分かりやすい制御フロー、実装の詳細をそのまま写した長いブロックは対象外にしてください。

回答に関する期待事項

• ユーザーがリファクタリングも依頼していない限り、差分はドキュメントに限定してください。
• 編集後は、追加、修正、削除したコメント、対象外とした主な項目、検証内容、そして自信を持って文書化するには不明確なまま残ったコードについての具体的な質問を簡潔に報告してください。