XMLコメントは必要なドキュメントですか？

私はかつて、ドキュメントにXMLコメントを要求するファンでした。それ以来、私は2つの主な理由で考えを変えました。

1. 優れたコードのように、メソッドは自明でなければなりません。
2. 実際には、ほとんどのXMLコメントは無意味なノイズであり、付加価値はありません。

多くの場合、GhostDocを使用して一般的なコメントを生成しますが、これは役に立たないノイズとは次のことを意味します。

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

私には、それは明白です。とはいえ、含める特別な指示がある場合は、XMLコメントを絶対に使用する必要があります。

私はこの記事からのこの抜粋が好きです：

時々、あなたはコメントを書く必要があるでしょう。しかし、それは規則ではなく例外であるべきです。コメントは、コードでは表現できないものを表現している場合にのみ使用してください。エレガントなコードを記述したい場合は、コメントを削除し、代わりに自己文書化コードを記述してください。

コードがそれ自体で説明するのに十分でない場合にのみXMLコメントを使用すべきだと思うのは間違っていますか？

これは、XMLコメントによってかなりのコードが見苦しく見える好例です。それはこのようなクラスを取ります...

public class RawMaterialLabel : EntityBase
{
    public long     Id                      { get; set; }
    public string   ManufacturerId          { get; set; }
    public string   PartNumber              { get; set; }
    public string   Quantity                { get; set; }
    public string   UnitOfMeasure           { get; set; }
    public string   LotNumber               { get; set; }
    public string   SublotNumber            { get; set; }
    public int      LabelSerialNumber       { get; set; }
    public string   PurchaseOrderNumber     { get; set; }
    public string   PurchaseOrderLineNumber { get; set; }
    public DateTime ManufacturingDate       { get; set; }
    public string   LastModifiedUser        { get; set; }
    public DateTime LastModifiedTime        { get; set; }
    public Binary   VersionNumber           { get; set; }

    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

...そしてそれをこれに変えます：

/// <summary>
/// Container for properties of a raw material label
/// </summary>
public class RawMaterialLabel : EntityBase
{
    /// <summary>
    /// Gets or sets the id.
    /// </summary>
    /// <value>
    /// The id.
    /// </value>
    public long Id { get; set; }

    /// <summary>
    /// Gets or sets the manufacturer id.
    /// </summary>
    /// <value>
    /// The manufacturer id.
    /// </value>
    public string ManufacturerId { get; set; }

    /// <summary>
    /// Gets or sets the part number.
    /// </summary>
    /// <value>
    /// The part number.
    /// </value>
    public string PartNumber { get; set; }

    /// <summary>
    /// Gets or sets the quantity.
    /// </summary>
    /// <value>
    /// The quantity.
    /// </value>
    public string Quantity { get; set; }

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

    /// <summary>
    /// Gets or sets the lot number.
    /// </summary>
    /// <value>
    /// The lot number.
    /// </value>
    public string LotNumber { get; set; }

    /// <summary>
    /// Gets or sets the sublot number.
    /// </summary>
    /// <value>
    /// The sublot number.
    /// </value>
    public string SublotNumber { get; set; }

    /// <summary>
    /// Gets or sets the label serial number.
    /// </summary>
    /// <value>
    /// The label serial number.
    /// </value>
    public int LabelSerialNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order number.
    /// </summary>
    /// <value>
    /// The purchase order number.
    /// </value>
    public string PurchaseOrderNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order line number.
    /// </summary>
    /// <value>
    /// The purchase order line number.
    /// </value>
    public string PurchaseOrderLineNumber { get; set; }

    /// <summary>
    /// Gets or sets the manufacturing date.
    /// </summary>
    /// <value>
    /// The manufacturing date.
    /// </value>
    public DateTime ManufacturingDate { get; set; }

    /// <summary>
    /// Gets or sets the last modified user.
    /// </summary>
    /// <value>
    /// The last modified user.
    /// </value>
    public string LastModifiedUser { get; set; }

    /// <summary>
    /// Gets or sets the last modified time.
    /// </summary>
    /// <value>
    /// The last modified time.
    /// </value>
    public DateTime LastModifiedTime { get; set; }

    /// <summary>
    /// Gets or sets the version number.
    /// </summary>
    /// <value>
    /// The version number.
    /// </value>
    public Binary VersionNumber { get; set; }

    /// <summary>
    /// Gets the lot equipment scans.
    /// </summary>
    /// <value>
    /// The lot equipment scans.
    /// </value>
    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

コメントが次のようにしか表示されない場合：

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

そう、それらはそれほど有用ではありません。彼らがこのようなものを読んだ場合：

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

それから私はそれらに価値があると言います。だからあなたの質問に答えるために：コードが言っていない何かを彼らが言うとき、コメントは必要です。

例外：一般に公開されるライブラリ/ APIを作成している場合は、一般公開されているものすべてにコメントを付けることをお勧めします。私が嫌いという名前の関数ライブラリを使用して見てgetAPCDGFSocket()APCDGFSocketが何であるかの説明なしでは（私は簡単なようなものと幸せになると思いますThis gets the Async Process Coordinator Data Generator File Socket）。したがって、その場合は、ツールを使用してすべてのコメントを生成し、それを必要とするコメントを手動で微調整します（そして、不可解な頭字語が説明されていることを確認してください）。

また、ゲッター/セッターは一般に「コメントが必要ですか？」の悪い例です。なぜなら、それらは通常非常に明白であり、コメントは必要ないからです。アルゴリズムを実行する関数では、コメントがより重要です。その理由は、物事が実際に行われている理由を説明することで、コードをより理解しやすくし、将来のプログラマーが作業しやすくなるためです。

...そして最後に、この質問は、XMLを使用してフォーマットされたもの（.NET環境で作業しているために使用しているもの）だけでなく、すべてのスタイルのコメントに関連していると確信しています。

コードを読むことができるユーザーには役に立たないように見えるコメントは、ソースにアクセスできないユーザーにとってはかなり役に立ちます。これは、クラスが組織外の人々によって外部APIとして使用されている場合に発生します。XMLドキュメントから生成されたHTMLが、クラスについて学習するための唯一の方法です。

とはいえ、単語間にスペースが追加されたメソッド名を繰り返すコメントは、依然として役に立たないままです。クラスが組織外で使用される場合は、値の有効範囲を少なくとも文書化する必要があります。たとえば、UnitOfMeasuretoの設定nullは無効である、セッターに提供される値には文字列の最初または最後にスペースを含めてはならない、などと言う必要があります。またLabelSerialNumber、プレーンの範囲と異なる場合の範囲も文書化する必要がありますInt32。おそらく負の数は許可されません^*、または7桁を超えることはできません。内部ユーザーは連日シリアル番号を毎日見るので当然のことと思うかもしれませんが、外部ユーザーは無実のセッターのように見えるものからの例外を見て本当に驚いているかもしれません。

あなたはそのような役に立たないコメントを避けることについて完全に正しいです。コードを読みやすくするのではなく、読みにくくし、スペースを取りすぎます。

私の実践では、ゲッター/セッターでコメントを書く人々は、それらが本当に必要な場合はコメントを省略する傾向があります（ドキュメントのないコンポーネントの20行のsqlクエリを作成するなど）。

他に明らかな解決策がある場合はコメントを書く_このアプローチが正確に使用された理由を示します。または、すべての詳細を知らずにアイデアを得るのが難しい場合は、コードを理解するために必要な詳細を簡単に示します。

あなたが持っている例は、他の人（そして彼らの人も）の生活を楽にするのではなく、コメントを書くというよりもコメントを書くことです。

ところで、古いコードに戻って理解しようとすることで、コメントを書く能力を向上させることができます（2〜3か月で自分のコードを認識できない可能性があります。他の人のコードを読むようなものです）。あなたがこれを無痛で行うなら、すべてがうまくいくよりも。