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

Question

我必须为C＃编写类似样式指南的内容，而且我现在正处于需要弄清楚哪些注释有意义而哪些注意没有意义的地方。我正在使用Robert C. Martin撰写的“清洁代码”一书和其他一些关于C＃的书（如O'Reillys c＃4.0）等等......但我找不到关于命名空间的评论......嗯......说实话，我找不到评论命名空间的任何好理由。另一件事是我想使用Visual Studio附带的XML文档，并且没有名称空间的默认实现。

你有充分的理由吗？

Answer 1

查看this MSDN page about the System.Data namespace

它提供了对此命名空间中的类的期望的一个很好的概述，并显示了它们一起工作的方式。

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

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

Answer 2

命名空间文档可以涵盖两个方面（恕我直言，适当时）：

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

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