web-dev-qa-db-ja.com

XMLコメントでC＃コードを文書化するためのベストプラクティスは何ですか？

私が書いたばかりのいくつかの新しいコードと、クラスとメソッドにNDocスタイルコメントを追加します。参考として、かなり良いMSDNスタイルのドキュメントを生成したいと思っています。

一般に、クラスとメソッドにコメントを書くときの良いガイドラインは何ですか？ NDocコメントは何を言うべきですか？彼らは何を言ってはいけないのですか？

.NET Frameworkのコメントの内容を調べているのですが、古くなります。自分自身をガイドするための良いルールがあれば、ドキュメントをはるかに早く完成させることができます。

c#code-documentationndoc
37
Esteban Araya

APIドキュメントの作成に使用するコメントでは、次のことを行う必要があります。

  • メソッドまたはプロパティが何をするか、なぜそれが存在するのか、およびコードの平均的な消費者には自明ではないドメインの概念を説明します。

  • パラメータのすべての前提条件をリストします（nullにすることはできません。特定の範囲内にある必要があります）。

  • 呼び出し元が戻り値を処理する方法に影響を与える可能性のある事後条件をリストします。

  • メソッドがスローする可能性のあるすべての例外（およびどのような状況下）をリストします。

  • 同様の方法が存在する場合は、それらの違いを説明してください。

  • 予期しない何か（グローバル状態の変更など）に注意を向けます。

  • 副作用があれば列挙します。

55
Jeff Sternal

価値のないコメントになってしまうと、無駄になってしまいます。

例えば

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

...値をまったく追加せず、維持するコードを追加しただけです。

これらの余分なコメントがコードに散らばっていることが多すぎます。

18
CaffGeek

StyleCop は、コードおよびコメントスタイルのヒントを提供します。それが与える提案は、MSDNドキュメンテーションスタイルに沿っています。

コメントの内容については、コードのユーザーに、どのような動作を期待できるかについて十分な情報を提供する必要があります。また、ユーザーが持つ可能性のある潜在的な質問にも答える必要があります。したがって、コードについて何も知らない人としてコードを使用するようにしてください。あるいは、より良い方法として、他の人にそうするように依頼してください。

6
Niels van der Rest

有効なXMLとは何かを忘れないでください。例えば：

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

（エラー：無効なXML）。

5
Pavel Radzivilovsky

プロパティの場合、コメントには、プロパティが読み取り専用か、書き込み専用か、読み取り/書き込みかを示す必要があります。すべてのMSの公式ドキュメントを見ると、プロパティドキュメントのコメントは常に「Gets ...」、「Gets or sets ...」、および（ほとんどの場合、プロパティのみの書き込みを避けて）「Sets ...」で始まります。

5
Matt Greer

<summary>コメントを記述して、自分がその関数を呼び出している（またはそのクラスをインスタンス化している）かどうかを知りたい情報を含めます。

<remarks>コメントを記述して、その関数またはクラスのデバッグまたは拡張のタスクがあったかどうかを知りたい情報を含めます。注：これは、適切なインラインコメントの必要性を置き換えるものではありません。ただし、関数/クラスの内部動作の概要が非常に役立つ場合があります。

2
mikemanne

MSDNページ に記載されているように、XMLドキュメントのコメントを使用してドキュメントを自動的に生成するため、APIを作成していて、コードとドキュメントの両方で2度作業したくない場合、それらの同期を保つことの追加の利点-コードを変更するたびに、適切なコメントを変更し、ドキュメントを再生成します。

/docでコンパイルすると、コンパイラはソースコード内のすべてのXMLタグを検索してXMLドキュメントファイルを作成し、次に Sandcastle などのツールを使用して完全なドキュメントを生成します。

0
luvieere

コメントについての1つのことは、コメントを更新することです。関数を変更する人が多すぎて、変更を反映するためにコメントを変更しないでください。

0
Brian