Adding Class Descriptions To Code?

Question

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

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

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

Answer 1

是的,您应该使用普通的XML文档:

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

这样它将显示在Intellisense中,如果您使用Sandcastle/ndoc/Doxygen等构建文档,它将显示得恰当.

如果在类上方的行中键入"///",您应该会看到一个合适的模板来开始.有关更多信息,请参阅上面的MSDN链接.

Answer 2

使用XML文档注释:

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

当您键入三个斜杠时,Visual Studio将帮助您完成其余的工作.

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