C#XML注释：有多少<；看/&燃气轮机；XML注释中的引用有用吗？

在我们公司，我们写过多的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);

//
///确定是否包含特定的。
/// 
///要在此中定位的。
/// 
///如果在中找到，则返回；否则。
/// 
bool包含（ISchedule schedule）；
/// 
///删除并删除第一次出现的特定
///从这个。
/// 
///要从中删除。
///当参数schedule为null时引发。
///在中找不到或类型错误时引发。
无效清除（计划时间表）；

正如您可以看到的，几乎每个名词都可以使用

标记引用。
我觉得这太过分了。我们的大多数代码文件都被这样的注释弄得一团糟。使评论部分几乎无法阅读

你觉得怎么样？您是否喜欢代码中的此类文档

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

编辑：
我的问题不是see-ref标记本身在默认情况下是否有用。显然，.chm文件（或任何其他类型的生成文档）中生成的链接非常有用。我的问题是，在评论中标记每个“可链接”名词的每次出现是否真的有用。

---

我们每晚都使用Sandcastle生成docu。不幸的是，其他开发人员很少使用它，但这是另一个问题

所有这些的要点是，当使用诸如Sandcastle之类的工具为库生成HTML或CHM文档时，这些文档可以在对象之间进行超链接导航。因此，问题是，当您使用MSDN时，您是否发现能够单击类名并将其导航到该类的帮助有用，或者您是否可以将其复制并粘贴到搜索字段中

---

是的，它会使代码膨胀（虽然注释可以折叠），但是如果你真的将文档发送给其他人，它会非常有用。

这类注释有一个特殊的原因：它们可以用来生成文档或为自动完成添加额外的信息。我同意它们过于冗长，在大多数情况下都难以阅读，但它们很适合添加到要对外公开的接口中

我建议使用一个编辑器，允许您打开和关闭评论

---

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

就个人而言，我认为您的做法有些过火

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

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

<see langword="true"/>

我个人认为，指向库中其他相关对象的超链接是非常有用的功能。它使阅读帮助对用户更有用

指向语言元素的超链接我觉得应该只存在于语言帮助本身中。在第三方图书馆的情况下，这只是通过到处放置链接来“混淆”信息。这会降低好链接的效率，因为它们会隐藏在混乱中

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

---

相信您的用户能够理解基本框架，但要向他们介绍您的库。

正如ctacke所说，它对于超链接非常有用。但是，如果您实际上没有发送文档，那么所有这些标记都会使文档几乎无法阅读。在这种情况下，文档是为（edit:INTERNAL）开发人员准备的，如果他或她看不懂文档，那就是在浪费时间

---

通常，我倾向于第一次引用某个类型或成员，而不链接其他类型或成员。它使评论非常干净，并且仍然提供有意义的链接。

当您使用Visual Studio时，您可以使用CR_Documentor插件（它是免费的，您可以获得）来读/写您的评论。它看起来像是从Sandcastle或NDoc生成的帮助，但是动态渲染的。

---

它非常有用，而且您根本不必关心原始xml注释。

当使用ReSharper的“快速文档”功能时（在我的键映射中按Ctrl-Q键），它也非常有用。听起来很有趣。可以说，我的库的使用者现在至少应该使用内置语言标记。好的观点。是的，当我看到到处都有与BCL链接的文档时，我觉得这是“说教”。这样做只是假设您的用户不理解他们在做什么。是的，这就是为什么使用

null

将其作为属于编码语言语法的关键字来区分比使用

“see”

引用更可取的原因。最后一句话令人惊讶。