メソッドの目的が値を計算して返すことである場合、私は次のように文書化しています。
/// <summary>
/// Calculates the widget count.
/// </summary>
/// <param name="control">The control to calculate the widget count of.</param>
/// <returns>The widget count.</returns>
ここで、returnsタグは新しい情報を提供しません: summary. (例外は を返すメソッドで、との戻り値の意味をbool簡単に説明できます。)truefalse
何か不足していますか？summaryとreturnsタグの間の繰り返しを避けるために XML ドキュメント ブロックを表現する標準的な方法はありますか?
ドキュメントは、特にプロパティで繰り返される傾向があります（外部の呼び出し元にとっては、単純な値のように見える必要があるため、「summary」と「value」の両方のエントリを提供することに意味がありません）。
そのため、繰り返し性を減らすために、summaryとparam / returns/valueなどを区別するようにしています。要約では、メソッドの機能（ウィジェット数の計算）について簡単に説明し、param / returns / valueでは入力/出力の詳細を示します（その他は何もありません）。多くの場合、エントリ間にさらに顕著な違いが見られます。例を読むと、ドキュメントが答えていないAPIについてすぐに質問があるので、これらの選択肢の1つに似たものを見たいと思っています。
/// <summary>Recursively calculates the widget count for a given control.</summary>
///
/// <param name="control">The root control of the subtree to process, or null.</param>
///
/// <returns>
/// The number of widgets that are contained within 'control' and its
/// entire subtree of descendant controls (or 0 if control is null).
/// </returns>
また...
/// <summary>Calculates the widget count for a given control.</summary>
///
/// <param name="control">The control to process. May be null.</param>
///
/// <returns>
/// The number of widgets that are direct children of 'control', or
/// -1 if it is null/not a registered control.
/// </returns>
あるいは ...
/// <summary>
/// Calculates the widget 'count' for a given control using the
/// Wicker-Bartland meanest minimum average algorithm.
/// </summary>
///
/// <param name="control">
/// The Wicker-Bartland control-input-value, in the range 1.0 .. 42.6
/// </param>
///
/// <returns>
/// The widget count, in the range -2PI .. +2PI, or Double.NaN if the
/// input control value is out of range.
/// </returns>
@Bertieが示唆しているように見えるものとは異なり、私は常に冗長性を減らし、情報コンテンツを増やすようにしています-メソッドが何をするかを知っているので、それが何のためであるかを説明するためにパラメーターの説明にそれほど詳細を必要としないかもしれません。多くの場合、非常に明白で直感的ですが、読者が最適な使用方法を理解できるように、有効な値やパラメーターの使用方法に関する詳細を追加できることがよくあります。同様に、どのような種類の戻り値を取得するかについての詳細（たとえば、ゼロ、負の値、nullなどを返す可能性があるかどうか）
このドキュメントは、コードコントラクトを定義するものと考えてください。コントラクトを明示的に記述するほど、コントラクトのあいまいさが少なくなり、別のプログラマーが、ソースコード。または、メソッドの動作が意図したとおりであるかバグであるかを特定します。または、既存の呼び出しコードを壊すことなく、メソッドの動作をどれだけ変更できるかを知ってください。
もちろん、場合によっては、メソッドが本当に単純で明白であるため、AtomineerUtilsでコメントして先に進むだけで、より重要な作業にかかる時間を節約できます。多くの場合、プログラミングは、実用的（作業を完了して製品を出荷する）と理論的理想（DRYなど）を満たすことの間のバランスである必要があります。
また、詳細には触れずに、メソッドの動作に関して要約をもう少し冗長にすることもできます。例えば
/// <summary>
/// Using the <paramref name="control"/> parameter, calculate the total number of widgets it contains.
/// </summary>
/// <param name="control">The control to calculate the widget count of.</param>
/// <returns>The total widgets contained in <paramref name="control"/>.returns>
場合によっては、戻り値についてもう少し説明が必要になることがあります。試してみて、どのように見えるかを確認してください。基本的に、コードを見ずに使用しなければならない API の一部として、誰かがこのドキュメントをあなたに渡したと想像してください。