39

作成したばかりの新しいコードを調べて、NDoc スタイルのコメントをクラスとメソッドに追加しています。参照用にかなり優れた MSDN スタイルのドキュメントを生成したいと考えています。

一般的に、クラスやメソッドにコメントを書く際の良いガイドラインは何ですか? NDoc コメントは何を言うべきですか? 彼らは何を言うべきではありませんか？

.NET フレームワークのコメントに書かれている内容を見ていると、すぐに古くなってしまいます。自分自身を導くための良いルールがあれば、ドキュメントをはるかに速く完成させることができます.

4

8 に答える 8

58

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

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

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

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

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

  • 類似の方法がある場合は、それらの違いを説明してください。

  • 予期しないこと (グローバル状態の変更など) に注意してください。

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

于 2010-06-29T17:58:55.253 に答える
17

何の価値もないコメントになってしまったら、それはただの無駄遣いです。

例えば

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

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

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

于 2010-06-29T17:51:08.590 に答える
6

StyleCopは、コードとコメント スタイルのヒントを提供します。提供される提案は、MSDN ドキュメント スタイルに沿ったものです。

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

于 2010-06-29T18:03:06.090 に答える
5

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

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

(エラー: 無効な XML)。

于 2010-06-29T21:24:42.703 に答える
5

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

于 2010-06-29T17:51:48.090 に答える
3

<summary> コメントを書いて、私がその関数を呼び出した (またはそのクラスをインスタンス化した) 場合に知りたい情報を含めます。

<remarks> コメントを書いて、関数やクラスのデバッグや強化を任された場合に知りたい情報を含めます。注: これは適切なインライン コメントの必要性を置き換えるものではありません。ただし、関数/クラスの内部動作の一般的な概要が非常に役立つ場合があります。

于 2010-06-29T21:19:44.520 に答える
0

MSDN ページに記載されているように、XML ドキュメント コメントを使用してドキュメントを自動的に生成するため、API を作成していて、コードとドキュメントの両方で 2 回作業したくない場合は理にかなっています。同期 - コードを変更するたびに、適切なコメントを変更してドキュメントを再生成します。

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

于 2010-06-29T17:57:39.317 に答える
0

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

于 2010-06-29T17:58:46.860 に答える