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-communication:simple-english practical）、執筆中はそのルールに従ってください。最初のドキュメントブロックを書く前に活用してください。書き終えた文章を後から書き直すより、最初から適切に書くほうが手間はかかりません。

ドキュメントブロックでは、特に次の点が変わります。

• ファイル全体で、概念ごとに使う語を統一します。 @param に「validate」とあり、要約に「check」とあると、読者には別々の操作に見え、違いを調べることになります。
• 説明文は25語、命令文は20語までです。 要約がそれを超える場合、複数の事実を含んでいるため、@remarks に記載します。一般的な幅では、先に1行の長さの上限に達します。そのため、語数は上限の目安とし、実際の行の表示幅で確認してください。
• can、will、must を使い、should は使いません。 呼び出し元がソート済み配列を「should」渡すという契約では、そのルールが必須かどうか読者にはわかりません。「must」と明記するか、渡さなかった場合に何が起きるかを記述してください。
• 結果より先に条件を書きます。 「retries が 0 の場合、呼び出しはただちに失敗します」という文は、逆の順序より適切です。読者は結果を読む前に、自分に当てはまる条件かどうかを判断できます。
• 測定値の裏付けがない形容詞は使いません。 「効率的にキャッシュします」では意味がありません。上限を示すか、その語を削除してください。

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

規約

• コードシンボルの要約は三人称で書きます — 「計算します…」「検索します…」「新しい…を初期化します…」など、Microsoft API リファレンスの規約に合わせます。例外として、手順を示すインラインの // コメントと、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	ドキュメントの監査、ドキュメント健全性レポートの作成