在代码中添加类描述？答案

【问题标题】：Adding Class Descriptions To Code?在代码中添加类描述？
【发布时间】：2011-03-14 20:22:54
【问题描述】：

我正在完成一个我已经工作了一段时间的项目，并且正在进行最后的润色。

我想做的一件事是在每个类文件的顶部添加类描述（以帮助我自己和其他程序员弄清楚发生了什么）。我的想法是用一堆'/'来拉出一个部分让我写一些笔记，但也许有更好的方法？在 Visual Studio 中是否有内置方法可以做到这一点？

/////////////////////////////////////////////////////
//                                                 //
// KillZombies.cs                                  //
//                                                 //
// Description: This class contains blah blah blah //
//                                                 //  
/////////////////////////////////////////////////////

【问题讨论】：

标签： c# comments

【解决方案1】：

是的，你应该使用普通的XML documentation：

/// <summary>
/// Describe your class quickly here.
/// </summary>
/// <remarks>
/// Add more details here.
/// </remarks>

这样它将显示在 Intellisense 中，如果您使用 Sandcastle/ndoc/Doxygen 等构建文档，它将正确显示。

如果您在班级上方的行中键入“///”，您应该会看到一个合适的模板以开始使用。有关详细信息，请参阅上面的 MSDN 链接。

【讨论】：

非常好。我使用“///”来描述我的方法，但不确定它是否也适用于整个类。
我应该把它放在我班级周围的 Namespace 声明之外还是里面？
@Aaron：在里面 - 它描述的是类，而不是命名空间，所以它应该在命名空间声明中。

【解决方案2】：

使用XML documentation comments:

/// <summary>
///  This class performs an important function.
/// </summary>

当您键入三个斜线时，Visual Studio 将帮助您完成其余的工作。

不要使用花哨的 ASCII 格式，因为当您重构以更改类名时，您将花费很长时间重新格式化所有框以使它们再次整齐排列。

【讨论】：

我应该把它放在围绕我的班级的命名空间声明之外还是里面？

【解决方案3】：

上述答案中描述的 XML 文档 cmets 是记录类和方法的方法。

如果您需要在每个文件中为非文档文本提供其他信息，例如创建日期、制作人员名单、版权信息等，您可以将其添加为 sn-p 或将其添加到相应的 Visual Studio 模板中。 VS 有用于模板的特殊变量，例如 $username$ 和 $time$，每次您根据模板添加新项目时，它们可用于自动插入这些值。

【讨论】：