Question

在我们公司，我们写了过多的Xml评论。一个典型的方法必须记录如下：

/// <summary>
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param>
/// <returns>
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>.
/// </returns>
bool Contains(ISchedule schedule);

/// <summary>
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/>
/// from this <see cref="IScheduler"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param>
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception>
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception>
void Remove(ISchedule schedule);

您可以看到几乎所有可以使用<see cref>标签引用的名词我觉得这太过分了。我们的大多数代码文件都被这样的评论搞得一团糟。使评论部分几乎不可读。

你怎么看？你喜欢这种代码中的文档吗？

像往常一样，我认为对这样一个问题没有黑/白的答案，这就是为什么我把它做成维基。

编辑：
我的问题不是，如果see-ref-tags本身默认有用。很明显，.chm文件（或任何其他类型的生成的文档）中生成的链接非常有用。我的问题是，如果在评论中标记每个“可链接”名词的每一个出现都是非常有用的我们每晚都使用Sandcastle生成文档。不幸的是，其他开发人员非常使用它，但这是另一个问题。

Answer 1

就个人而言，我认为你所拥有的有点落伍。

“see”引用的目的是在解析后在生成的帮助文档中提供主题之间的良好链接。

在您的情况下，您的业务特定库引用语言项，即：

<see langword="true"/>

我个人觉得到库中其他相关对象的超链接是一个非常有用的功能。它使阅读帮助对您的用户更有用。

语言元素的超链接是我认为应该只存在于语言帮助本身内部的东西。在第三方图书馆的情况下，这只是通过在任何地方放置链接来“混淆”消息。这使得良好的链接效率降低，因为它们隐藏在混乱中。

我建议自由使用链接到库中的相关类。我会避免添加到基本库类的超链接，除非在特定情况下由于某种原因特别有用（罕见）。链接到“true”和“IDisposable.Dispose”等，并没有真正增加很多价值。

相信您的用户了解基础框架，但教他们关于您的库。

Answer 2

所有这些的重点在于，当使用像Sandcastle这样的东西为库生成HTML或CHM文档时，那些文档会在对象之间获得超链接导航。那么问题就是，当你使用MSDN时，你会发现能够点击一个类名，导航到该类的帮助是否有用，或者你可以将它复制并粘贴到搜索字段中吗？

是的，它会使代码膨胀（尽管注释可能会崩溃），但如果您实际上将文档发送给其他人，那么它会非常有用。

Answer 3

当您使用Visual Studio时，您可以使用CR_Documentor插件（它是免费的，您可以获得它here）来阅读/撰写您的评论WYSiWYG。看起来像生成的帮助形成Sandcastle或NDoc，但是在运行中呈现。它非常有用，您根本不必关心原始xml注释。

Answer 4

正如ctacke所说，它对超链接非常有用。但是，如果您实际上没有提供文档，那么所有标记都会使文档几乎无法读取。在这种情况下，文档是针对（编辑：内部）开发人员的，如果他或她无法阅读，那么你就是在浪费时间。

作为一项规则，我倾向于首先引用某个类型或成员，并将其余内容取消链接。它使评论非常干净，并且仍然提供有意义的链接。

Answer 5

这些评论有一个特殊原因：它们可用于生成文档或向自动完成添加额外信息。我同意它们在大多数情况下都过于冗长且难以阅读，但它们很适合添加到您将在外部公开的界面。

我建议使用一个允许您打开和关闭注释的编辑器。

有些语言允许您将注释存储为变量和函数的元数据，这是一个不错的选择。

C＃XML注释：XML注释中有多少<see ... =“”>引用有用吗？</see>

5 个答案: