documentation

ドキュメント

Microsoft のコントラクトファーストの規約です。ドキュメントにはコントラクト、つまり何をするのか、なぜそうするのかを記載し、内部でどのように動作するかは記載しません。

ルールが削ぎ落とすものである理由

コードは変更されますが、その隣にあるコメントはたいてい変更されません。時間がたつとドキュメントは事実と異なる内容になり、それでも読者は信じてしまいます。古くなったコメントは、積極的に誤解を招くため、コメントがないよりも悪いものです。ここから二つの習慣が導かれ、以下のルールはすべて、そのいずれかを適用したものです。

表面を小さく保ちます。 文章が少ないほど、古くなりにくくなります。コメントは最後の手段であり、最初に行うことではありません。書く前に、より明確な名前、小さな関数、名前付きの型で意味を伝えられないか考えてください。文章を使うのは、コードではどうしても表現できない残りの部分です。

**各事実は一か所だけに、**それを所有するコードの隣に記載し、更新が必要な箇所を必ず一つにします。シグネチャ、型、テストですでに示されている内容を、文章で繰り返してはいけません。

必要最小限のルール

シグネチャにはすでに、名前、パラメーター名と型、戻り値の型、修飾子（readonly、?、async）が含まれています。ドキュメントに追加するのは、読者がシグネチャから推測できない内容だけです。意図、単位、範囲、デフォルト値、境界値の意味、エラーケース、不変条件などです。

生成されるドキュメントや IDE のツールチップに内容が表示されるよう、すべての公開メンバーには簡潔な要約を付けます。シグネチャを言い換えるのではなく、意図を伝える短い一文にしてください。

特に @param と @returns については、シグネチャを繰り返すだけならタグ自体を省略してください。 タグを付ける価値があるのは、次のような問いに答える場合です。単位は何か。範囲や上限は何か。省略時のデフォルト値は何か。境界値は何を意味するか（0 は無効化、-1 は無制限、空はすべて）。null は例外のスローとどう異なるのか。

@throws は反対の方針です。コードが例外をスローする可能性がある場合は、必ず記載してください。どの例外がスローされるかは、シグネチャからは分からないためです。

ドキュメントブロックの形式

ドキュメントブロックは、IDE のツールチップ、ホバーカード、コードレビューの差分など、冒頭が表示されて残りが省略される場所で読まれます。そのため、分量は文の数ではなく、表示される行数で数えます。

• 要約 — ちょうど1行。 意図を伝える一文だけをブロックの先頭に置きます。2行にしたり、2文にしたりしてはいけません。
• 詳細 — 最大3行。 空行の後に記載し、要約だけではコントラクトを本当に伝えられない場合に限ります。主な考えだけを記載します。処理の分岐ではなく、操作の内容とそれを規定する制約を記載します。
• インラインの // または # コメント — 最大3行、できれば1行。

行数を超えた場合、折り返しを調整して解決してはいけません。内容を記載する場所が間違っているということです。分岐ごとの動作、境界ケース、制約の理由は @remarks に記載します（Python では Note: / Notes）。この記述があることで、ブロックの冒頭を読みやすく保てます。

フォーマッター適用後に数えます。適用前ではありません。 ブロックを書いたら、プロジェクトのフォーマッターで設定済みの幅に整形します（検出順序は Conventions を参照）。その後、出力された行数を数えてください。要約が折り返されて2行になった場合は、予算を超えています。1行に収まるまで言葉を削ってください。2文目に分けてはいけません。そうすると、要約の装いをした詳細になってしまうためです。フォーマッターや max-len ルールによって3行を超えたインラインコメントにも、同じ確認を行います。

散文の読みやすさ

ここで書くすべての文、つまり要約、残す @param の説明、@throws の条件、エンドポイントの説明は、読者がデバッグの最中に読むものです。その人があなたと同じ第一言語を使うとは限りません。simple-english スキルを実用的なレベルで読み込み（/cortex:simple-english practical）、執筆中はそのルールに従ってください。最初のドキュメントコメントを書く前に使いましょう。すでに書いた散文を後から書き直すより、最初から正しく書くほうが手間はかかりません。

ドキュメントコメントにおける具体的な変更点は次のとおりです。

• ファイル全体で、概念ごとに単語を一つに統一します。 @param で「検証する」と書き、要約で「確認する」と書くと、読者には別々の操作のように見え、その違いを探し始めてしまいます。
• 説明文は25語、命令文は20語までです。 これを超える要約には複数の事実が含まれているため、@remarks に移します。通常の行幅では一行の文字数制限が先に効くため、語数は上限の目安とし、実際に表示された行で確認してください。
• can、will、must を使い、should は使いません。 呼び出し元はソート済みの配列を「should」渡すべきだ、と書かれた契約では、その規則が必須なのか読者には判断できません。must と書くか、渡さなかった場合に何が起きるかを説明してください。
• 結果より先に条件を書きます。 「retries が 0 の場合、呼び出しはただちに失敗します」という文は、条件と結果を逆にするより明確です。読者は結果を読む前に、その文が自分に当てはまるかを判断できます。
• 根拠となる測定値のない形容詞は使いません。 「効率的にキャッシュする」では何も伝わりません。上限値を示すか、その言葉を削除してください。

識別子、コードサンプル、引用されたエラー文字列はそのままにします。標準ではこれらを技術的な名称として扱うため、「修正済み」のものをコピーした読者が新たなエラーに遭遇する可能性があります。

規約

• コードシンボルの要約は三人称で書きます —「計算します…」「検索します…」「新しい…を初期化します」など、Microsoft API リファレンスの規約に合わせます。命令形を使う例外は2つあります。手順を示すインライン // コメントと、API 操作の summary フィールド（OpenAPI、@ApiOperation、extend_schema）です。後者では「新しいユーザーを作成する」が確立された形式です。
• インターフェースには抽象化の内容を記述します。目的、発生するエラー、戻り値の意味、不変条件を記載します。キャッシュ、クエリ、アルゴリズムなどの実装詳細は実装に記載します。インターフェースを読む利用者に、リファクタリングで無効になる可能性のある情報を知らせてはいけません。
• データ構造には「何か」を記述し、「なぜか」は記述しません。 DTO、レコード、構造体、またはそれを定義する interface／type では、各メンバーが 何であるか、つまり意味、単位、形式、許容値、型では表せない制約を説明します。そのフィールドが存在する理由は説明しません。関数の契約には操作の理由が含まれますが、データフィールドは使用時に読まれるものです。そのため、「請求内容を照合できるように保持する」といった設計上の理由は古びやすく、そのフィールドを生成または使用する動作の説明に含めるべきです。例外として、保守担当者が破ってはいけない、ひと目では分からない制約には、必要最小限の @remarks を使います。これを通常の説明にはしません。
• インターフェースの内容を実装に繰り返しません。 (@inheritDoc または言語に相当する機能で) 継承し、実装固有の説明だけを追加します。
• 複数行のドキュメントコメントだけを使います。 すべての /** の後は、本文を次の行から始めます。1行の /** … */ は使いません。
• 明示的に求められない限り、リリースタグ（@public、@beta、@alpha、@internal）は使いません。
• テストスイートで実行される例だけを含めます。 実行されない例は実装とのずれが生じ、誤ったコメントがもう一つ増えることになります。実行される Python doctest（pytest --doctest-modules）は対象に含めます。TSDoc の @example ブロックはツールで実行されないため、省略し、動作はテストで示します。
• プロジェクトで設定された幅に合わせて折り返します。 次の順に確認します。.editorconfig の max_line_length → フォーマッターの設定（printWidth、line-length）→ リンターの設定（max-len、max-line-length）。いずれにも指定がない場合のみ、80 にします。

見つけたらすぐ削除するコメント

監査では、抜けを埋めるのと同じくらい、次のコメントを削除することが重要です。どれも、事実が古くなる可能性がある箇所です。

• コメントアウトされたコード — バージョン管理システムがすでに記録しているため、残しておくと、今も必要なのか読者を迷わせます。
• 作業記録や変更履歴のコメント（「2024-03 リトライロジックを追加」など）— git log で正確な情報を確認できます。
• 作成者を示す行（「…が追加」など）— git blame で確認できるため、古くなる心配もありません。
• バナー、位置を示すマーカー、閉じ波括弧のラベル（// ===== helpers =====、} // end if）— 構造はコード自体から把握できるようにします。
• 名前、型、シグネチャを言い換えるものや、明白なことを述べるもの（/** Default constructor */）。

ドキュメント作業の進め方

作業を始める前に、プロジェクトで使われている形式を確認してください（既存ファイルから判別してもかまいません）。また、フレームワークも特定してください。API ドキュメントの方針はフレームワークごとに異なるため、誤った方針を適用すると、誰にも利用されない仕様書ができてしまいます。

件数ではなく、健全性を報告してください。 すべてのメンバーにドキュメントブロックがあるファイルを目指すのではありません。ブロックの半分がシグネチャを言い換えているなら、なおさらです。改善した点を報告してください。冗長な記述の削除、古くなったドキュメントの修正、意図の要約や @throws の追加などです。網羅率は最低限の目安です。空のメンバーを見つけることはできますが、価値のあるブロックと中身のないブロックを見分けることはできません。

参考資料

参考資料	読み込むタイミング
references/python-docstrings.md	Python — Google、NumPy、または Sphinx スタイル
references/typescript-jsdoc.md	TypeScript/JavaScript — TSDoc タグ、@inheritDoc、書式
references/api-docs.md	REST API ドキュメント — NestJS、Express、FastAPI、Django
references/coverage-reports.md	ドキュメントの監査、ドキュメント健全性レポートの作成