3.4　从注释生成文档

不论内部项目还是为外部开发者开发的软件，为代码编写文档都是一个良好的实践。内部项目受开发者流动性差的影响，帮助新人快速熟悉上手的文档往往很少，甚至没有。而很多第三方API由于糟糕的开发文档，因此无人问津且推广缓慢，甚至难以使用而遭到现有用户的抛弃。

每个源代码文件的顶部都应当包含版权声明。命名空间、接口、类、枚举、结构体、方法和属性都应当包含注释。版权声明应当位于代码文件的顶部，using语句之前，并使用以/*开始和以*/结束的多行注释形式：

上述范例展示了带有文档注释的命名空间和类代码片段。其中，命名空间及其成员的文档注释以///开头，并直接位于被注释的项目的上方。在Visual Studio中，当我们键入三个斜杠字符时，编辑器会自动根据后续一行的内容生成XML标记。

例如，在上述代码中，命名空间和类仅仅包含摘要信息。而其中两个方法则含有摘要信息、若干参数注释以及返回值的注释。

表3-1列出了可以在文档注释中使用的各种XML标签。

表3-1　可以在文档注释中使用的各种XML标签

从上表可见，我们可以对源代码的方方面面编写文档。因此请充分利用这些标签来进行文档编写。文档越好，开发者就能越快越容易地熟悉并使用代码。

下一节将介绍内聚和耦合。