メソッドコメントには、よく似ている場合に、概要と戻り説明の両方を含める必要がありますか？

私は適切に文書化されたコードの支持者であり、そのコードの考えられる欠点をよく知っています。それはこの質問の範囲外です。

Visual StudioのIntelliSenseがどれだけ好きかを考慮して、すべてのパブリックメンバーにXMLコメントを追加するというルールに従うのが好きです。

ただし、冗長性には1つの形式があり、私のような過度のコメンターでさえも気になります。例として、List.Exists（）を取ります。

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summaryそして、returns基本的に同じことを言っています。私はしばしば、より完全returnsな観点から要約を記述し、returnsドキュメントを完全に削除することになります。

指定された述語によって定義された条件に一致する要素がリストに含まれている場合はtrueを返し、それ以外の場合はfalseを返します。

さらに、返品に関するドキュメントはIntelliSenseに表示されないため、すぐに関連する情報をに記述しsummaryます。

1. とはreturns別にドキュメント化する必要があるのはなぜsummaryですか？
2. マイクロソフトがこの標準を採用した理由に関する情報はありますか？

コードを確認または使用するときに、ユーザーが関心のあるセクションに焦点を合わせるのに役立つため、これらのセクションは別々に推測できます。

あなたの例を挙げれば、私はむしろ書きたいと思います：

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• このコードをレビューしていて、メソッドの機能を知りたい場合は、概要を読みます。それだけが気になります。

• ここで、私があなたのメソッドを使用していて、入力を受け取ったときに受け取る戻り値がおかしいと想像してみましょう。今、私はメソッドが何をするのかを知りたくありませんが、戻り値についてもっと知りたいです。ここでは、<returns/>セクションが役立ちます。要約を読む必要はありません。

ここでも、この例では、からサマリーを推測し、サマリーから<returns/>期待される戻り値を推測できます。ただし、同じ引数を極端に取ると、この場合はメソッドをまったく文書化する必要はありません。メソッドの名前は、内部List<T>に置かPredicate<T> matchれ、唯一の引数はそれ自体が非常に明示的です。

覚えておいて、ソースコードは、一度書かれたが、回をたくさん読まれます。コードをさらに読む人のために消費税を減らすことができ、XMLドキュメントに追加の文を10秒かけて書く場合は、それを行います。

私の使用法：メソッドが何をするかを
<summary>説明します（を取得するため<returns>）。戻り値を
<returns>説明します。

MSDNへのリンク：<summary>。<returns>

返品を要約とは別に文書化する必要があるのはなぜですか？

要約の部分が本当に長くて説明的なものである場合は、最後に別個の短い戻り値の部分があると便利でしょう。

私は通常<summary>、自分のコードにその部分だけを記述し、「Returns _」と言った方法で言います。

メソッド名とパラメーター（およびそれらの名前）からは明らかではないことを、呼び出し元が知っておく必要があるすべてのコメントを入れました。うまくいけば、メソッド名とパラメーターによって、コメントが非常に簡潔になることは明らかです。

私は最近同じ哲学的質問に引き裂かれました、そして私はまだ良い解決策が何であるかわかりません。しかし、これまでのところ、これは私のアプローチです...

• メソッドのドキュメントは、外部の呼び出し元が知っておくべきことだけを説明しています。この処理が内部でどのように行われるかについては触れていませんが、a）呼び出し元がこのメソッドを呼び出したい理由、b）メソッドを呼び出した場合の予期される結果について言及しています。メソッドがどのように機能するかを文書化する必要がある場合は、それをコード本体自体に入れます。
• メソッドに十分な複雑さがある場合、一般的な説明と個別の[returns]セクションは正当化されるようです。読者に説明全体を読んで戻り値の解釈方法を推測させたくないでしょう。
• メソッドが非常に単純なので、「このメソッドは人の住所を返す」のように説明するのが最善の方法です。追加するとDRYの原則に反するように見えるので、[returns]セクションをスキップします。それの巨大な擁護者。多くのワンライナーアクセサーメソッドがこのカテゴリに分類されるようです。

要約は、役に立つかもしれないほど説明的でなければなりません。パラメータと戻り値の説明は短くて簡潔でなければなりません。1つの単語と5つの単語から選択できる場合は、1つを使用します。あなたの例を引き締めましょう：

リストに、指定された述語で定義された条件に一致する1つ以上の要素が含まれている場合、trueです。それ以外の場合はfalse。

なる

Listのいずれかの要素が述語と一致する場合はtrue。それ以外の場合はfalse。