将类描述添加到代码?

时间:2010-07-12 14:17:33

标签: c# commenting

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

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

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

3 个答案:

答案 0 :(得分:33)

是的,您应该使用正常的XML documentation

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

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

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

答案 1 :(得分:6)

使用XML documentation comments

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

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

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

答案 2 :(得分:1)

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

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