c# - 为什么要为命名空间添加注释？

Question

我必须为 C# 编写类似样式指南之类的东西，而我目前正处于必须弄清楚哪些评论有意义而哪些没有意义的地步。我正在大量使用 Robert C. Martin 的“清洁代码”一书以及其他一些关于 C# 的书籍（如 O´Reillys c# 4.0）等等……但我找不到关于评论命名空间的词……嗯......老实说，我找不到任何好的理由来评论命名空间。另一件事是我想使用 Visual Studio 附带的 XML 文档，并且没有命名空间的默认实现。

你对我有充分的理由吗？

Answer 1

查看有关 System.Data 命名空间的 MSDN 页面

它很好地概述了这个命名空间中的类的期望，并展示了它们协同工作的方式。

因此，可能有充分的理由将有价值的文档添加到命名空间。

了解预期的类型、添加的类型以及如何使用它们可能非常有价值，因为很难在其他地方收集这些信息。

Answer 2

命名空间文档可以（恕我直言，在适当的情况下应该）涵盖两个方面：

• 在命名空间中可以找到什么？: 命名空间不是任意分组；一个命名空间中的类型通常有一些共同的主题。这种分类可以在命名空间注释中描述，因为单个命名空间标识符很少足够精确和明确。特别是如果命名空间包含一组旨在一起工作的特定类型，命名空间注释是描述如何一起使用这些类型的地方。（或者，它可以告知首先要实例化哪些类型，或者哪些类型是命名空间中最重要的类型。）
• 什么可以放在命名空间中？：如果命名空间旨在由第三方扩展（向其添加更多类型），则注释还应描述命名空间适用于哪些可能的未来类型，以及哪些不应该进入命名空间。例如，您可以指出命名空间YourCompany.Text适用于与字符串处理相关的类型，或者您可以指出它仅适用于YourCompany命名空间中某些内容的非常特定的插件类型。该信息不能仅从名称空间名称中推断出来。

更重要的是，如果您使用一些文档生成器将注释格式化为某种类型的手册（例如 Sandcastle 或 NDoc），命名空间页面（列出命名空间中所有类型的页面）将接收命名空间文档注释作为附加信息。获得一个简短的概述而不仅仅是一个单一的命名空间名称和一个（可能很长的）类型列表对于一个好的基于命名空间的文档来说是至关重要的。