C# ドキュメント ベストプラクティス

• Public メンバーは XML コメントでドキュメント化する必要があります。
• 特に複雑であったり自明でない場合は、internal メンバーのドキュメント化も推奨されます。

すべての API に対するガイダンス

• <summary> を使用して、型またはメンバーが何をするかについて簡潔な 1 文の説明を提供します。現在形、三人称で動詞を始めます。
• <remarks> を使用して追加情報を提供します。これには実装の詳細、使用上の注意、またはその他の関連するコンテキストを含めることができます。
• <see langword> を使用して、null、true、false、int、bool などの言語固有のキーワードを参照します。
• <c> をインラインコードスニペットに使用します。
• <example> をメンバーの使用方法の例に使用します。
  • <code> をコードブロックに使用します。<code> タグは <example> タグ内に配置する必要があります。language 属性を使用してコード例の言語を追加します。例えば <code language="csharp"> のようにします。
• <see cref> を使用して、他の型またはメンバーをインライン (文中) で参照します。
• <seealso> をオンラインドキュメントの「参照」セクションで、他の型またはメンバーへのスタンドアロン (文中以外) 参照に使用します。
• <inheritdoc/> を使用して、基底クラスまたはインターフェイスからドキュメントを継承します。
  • 重大な動作変更がない限り。動作に大きな変更がある場合は、その違いをドキュメント化する必要があります。

メソッド

• <param> を使用してメソッドのパラメーターを説明します。
  • 説明は、データ型を指定しない名詞句である必要があります。
  • 冠詞で始めます。
  • パラメーターがフラグ列挙型の場合、説明を「列挙値のビット単位の組み合わせで...を指定します」で始めます。
  • パラメーターが非フラグ列挙型の場合、説明を「...を指定する列挙値の 1 つです」で始めます。
  • パラメーターがブール値の場合、「<see langword="true" /> の場合は ...、そうでない場合は <see langword="false" />」という形式の文言を使用します。
  • パラメーターが「out」パラメーターの場合、「このメソッドが返されるとき、... が含まれます。このパラメーターは初期化されていないものとして扱われます」という形式の文言を使用します。
• <paramref> を使用してドキュメント内でパラメーター名を参照します。
• <typeparam> を使用してジェネリック型またはメソッドの型パラメーターを説明します。
• <typeparamref> を使用してドキュメント内で型パラメーターを参照します。
• <returns> を使用してメソッドの戻り値を説明します。
  • 説明は、データ型を指定しない名詞句である必要があります。
  • 冠詞で始めます。
  • 戻り値の型がブール値の場合、「<see langword="true" /> の場合は ...、そうでない場合は <see langword="false" />」という形式の文言を使用します。

コンストラクター

• サマリーの文言は「<クラス> クラス [または構造体] の新しいインスタンスを初期化します」である必要があります。

プロパティ

• <summary> は次で始まる必要があります:
  • 読み書きプロパティの場合、「取得または設定...」
  • 読み取り専用プロパティの場合、「取得...」
  • ブール値を返すプロパティの場合、「取得 [または設定] ... かどうかを示す値」
• <value> を使用してプロパティの値を説明します。
  • 説明は、データ型を指定しない名詞句である必要があります。
  • プロパティにデフォルト値がある場合は、別の文で追加します。例えば「デフォルトは <see langword="false" /> です」のように記述します。
  • 値の型がブール値の場合、「<see langword="true" /> の場合は ...、そうでない場合は <see langword="false" />。デフォルトは ...」という形式の文言を使用します。

例外

• <exception cref> を使用して、コンストラクター、プロパティ、インデクサー、メソッド、演算子、およびイベントによってスローされる例外をドキュメント化します。
• メンバーによって直接スローされるすべての例外をドキュメント化します。
• ネストされたメンバーによってスローされる例外については、ユーザーが遭遇する可能性が最も高い例外のみをドキュメント化します。
• 例外の説明は、その例外がスローされる条件を説明します。
  • 文の最初に「スローされる場合...」または「...の場合」は省略します。条件を直接述べます。例えば「Message Queuing API にアクセスするときにエラーが発生しました」のようにします。