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

StackOverflow https://stackoverflow.com/questions/3143324

  •  01-10-2019
  •  | 
  •  

質問

書いたばかりの新しいコードを調べて、クラスと方法にNDOC Sytleのコメントを追加しています。参照のために、かなり良いMSDNスタイルのドキュメントを生成したいと思っています。

一般に、クラスや方法のコメントを書くときの良いガイドラインは何ですか？ NDOCのコメントは何を言うべきですか？彼らは何を言うべきではありませんか？

.NETフレームワークのコメントが言っていることを見ているのですが、それは速く古くなります。自分自身を導くための良いルールがあるなら、ドキュメントをより速く完了することができました。

役に立ちましたか？

解決

APIドキュメントを作成するために使用されるコメントでは、次のようにする必要があります。

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

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

  • 発信者が返品値にどのように対処するかに影響を与える可能性のある条件をリストします。

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

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

  • 予期しないものに注意を喚起します（グローバル状態の変更など）。

  • ある場合は、副作用を列挙します。

他のヒント

価値を追加しないコメントになった場合、それらはただ無駄です。

例えば

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

...あなたは絶対に価値がありません、そして、維持するためにさらに多くのコードを追加しました。

多くの場合、コードにはこれらの余分なコメントが散らばっています。

stylecop コードのヒントを提供します と コメントスタイル。それが提供する提案は、MSDNドキュメントスタイルと一致しています。

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

プロパティの場合、コメントは、プロパティが読み取り専用か、書き込みのみであるかを示す必要があります。すべての公式MSドキュメントを見ると、プロパティドキュメントのコメントは常に「gets ...」、「gets or sets ...」から始まります（非常にまれに、通常はプロパティのみを避けることは避けてください）「セット...」

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

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

（エラー：無効なXML）。

私は書きますu003Csummary>私がその関数を呼んでいる（またはそのクラスをインスタンス化する）かどうかを知りたい情報を含めるためにコメント。

私は書きますu003Cremarks>情報を含めるために、その関数またはクラスのデバッグまたは強化を任されているかどうかを知りたいと思います。注：これは、適切なインラインコメントの必要性を置き換えません。しかし、関数/クラスの内側の仕組みの一般的な概要が非常に役立つ場合があります。

で述べられているように MSDNページ, 、XMLドキュメントのコメントを使用してドキュメントを自動的に生成するため、APIを書いていて、コードとドキュメントの両方で2回作業したくないかどうかを確認します。コードは、適切なコメントを変更し、ドキュメントを再生します。

コンパイルします /doc コンパイラはソースコードのすべてのXMLタグを検索し、XMLドキュメントファイルを作成し、次のようなツールを使用します 砂のお城 完全なドキュメントを生成します。

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

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top