是否需要XML注释文档？

我曾经是要求XML注释用于文档的爱好者。从那以后，我改变了主意，主要有两个原因：

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是了解类的唯一方法。

就是说，重申该方法名称并在单词之间添加空格的注释仍然没有用。如果您的班级将在组织外部使用，则需要至少记录下来您值的有效范围。例如，你应该说，设定UnitOfMeasure到null是非法的，是提供给二传手的价值不能在开头或字符串的结尾包含空格，等等。LabelSerialNumber如果与普通格式不同，还应记录以下范围Int32：也许不允许负数^*，或不允许超过七个数字。您的内部用户可能会认为这是理所当然的，因为他们日复一日地查看序列号，但是外部用户可能真的很惊讶地看到一个看起来像无辜的二传手的例外。

避免这种无用的评论是绝对正确的。它们使读取代码变得更加困难，而不是使代码变得更容易，并且占用了太多空间。

在我的实践中，使用getter / setter编写注释的人倾向于在确实需要注释时省略注释（例如为没有文档的组件构建20行sql-query）。

当有其他明显的解决方案时，我会写评论_我指出了为什么确实使用了这种方法。或者，如果在不了解所有细节的情况下很难理解这个想法，我将简要列出理解代码所必需的细节。

您带来的示例更多是在写评论，说一个人写评论而不是使他人（以及他们的）生活更轻松。

顺便说一句，您可以通过返回原来的代码并尝试理解它来提高编写注释的能力（您甚至可能在2-3个月内无法识别您自己的代码，这绝对就像阅读别人的代码一样）。如果您毫不费力地执行此操作，那一切就好了。