将类描述添加到代码？

Question

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

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

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

Answer 1

是的，您应该使用正常的XML documentation：

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

这样它会显示在Intellisense中，如果你使用Sandcastle / ndoc / Doxygen等构建你的文档，它会显示得恰到好处。

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

Answer 2

使用XML documentation comments：

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

当您键入三个斜杠时，Visual Studio将帮助您完成剩下的工作。

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

Answer 3

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

如果您需要在每个文件中提供非文档文本的附加信息，例如创建日期，信用，版权信息等，您可以将其添加为片段或将其添加到相应的Visual Studio模板中。 VS具有模板的特殊变量，例如 $ username $ 和 $ time $ ，可以在每次根据模板添加新项目时自动插入这些值。