在C#自动实现属性中，为什么要同时定义<summary>和<value>？

Question

C#规范/StyleCop（不确定哪个）建议在自动属性中加上两个标签--<summary>和<value>，例如：

class Foo
{
    /// <summary>Gets bar.</summary>
    /// <value>Bar.</value>
    public Example Bar { get; set; }
}

但实际上，<summary> 的价值始终是 获取 <此处输入的值>。

这个单独的标记是为了帮助特定的文档生成器，还是与编译器生成自动属性的方式有关，或者其他原因呢？

- Billy ONeal

---

如果你善于跳出框架思考，那么对于那些使用这些属性的人来说，它们自动实现的事实是未知的。在这里只是扮演魔鬼的拥护者... - Ilya Ivanov

我认为这只是一个规则。有趣的是，微软提供了一个看起来像这样的示例：<value>The Name property gets/sets the _name data member.</value>，但对于自动属性来说是无用的。Visual Studio不会自动添加此标记。 - Robert Harvey

@Robert：Visual Studio在一般情况下不会自动添加符合StyleCop标准的内容。 - Billy ONeal

我不知道那是什么意思。如果你说Visual Studio无法确定它是一个属性，也许你是对的。 - Robert Harvey

@Robert：不，我的意思是Visual Studio的自动文档生成器并不关心C#规范或StyleCop。StyleCop会因为各种Visual Studio认可的东西而失败。例如，如果一个具有公共getter和私有setter的属性没有以字符串“Gets”开头，那么StyleCop将会抛出错误。 - Billy ONeal

Answer 1

这两个标签的自动建议内容重复，正如您所指出的那样。但是，对于一个良好记录的类（例如作为公共API的一部分），应在这两个标签中放置不同的文本。

例如，让我们看一下Microsoft的公共API文档 DateTime.Date属性。

注释中的<summary>和<value>标签对应文档的两个不同部分。在这种情况下，文档可能是从类似以下注释生成的：

/// <summary>
///   Gets the date component of this instance.
/// </summary>
/// <value>
///   A new object with the same date as this instance, and the time value
///   set to 12:00:00 midnight (00:00:00).
/// </value>

因此，您可以看到“摘要”用于工具提示中，是属性的缩写摘要，而“值”是返回值的更详细描述。

阅读<summary>和<value>标签的完整文档以获取更多详细信息。

- Rich

---

啊，那么我放在摘要标签里的内容是错误的。我原本写的是“<summary>获取一个新对象，其日期与此实例相同，时间值设置为午夜12:00:00（00:00:00）。” - Billy ONeal