我应该在班级文件标头中包含什么

15

我正在寻找有关Entity，Business Logic和Data Access类的信息丰富的类文档格式。

我从这里发现以下两种格式

格式1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

格式2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

我觉得以下是基本要素

作者
创建日期
描述
修订记录

因为命名空间和类名称仍然会存在。

请让我知道您的想法，建议使用哪种格式以及是否存在编写修订历史记录的标准方法？

c# documentation comments

— 霍克
source

8

我认为，如果您使用某种形式的VCS，则修订历史很重要。通过将其放置在此处，可以增加您需要记住的另一个文档位置，为什么不让VCS为您做到这一点，并尽可能简化代码文档。

— 克里斯，2010年

5

作者和创建日期也由源代码管理处理。您只需要描述。

— Mike Seymour，2010年

27

您建议的大多数信息都可以在源存储库中找到。

您真正唯一需要的是目标部分，该部分说明了该类的用途。

每当您想了解其他信息时，在存储库中查找是否会很乏味？我会说不。您多久关心一次原始作者？还是首次创建文件时？插件（例如Visual Studio的Ankh SVN）通常允许您在当前文件中右键单击并查看该文件的存储日志，因此实际查看此信息并不麻烦。

此外，如果您将版本历史记录存储在注释中，则需要保留此注释。因此，随着时间的流逝，它可能会向您撒谎。源代码存储库会自动保留此历史数据，因此不需要进行维护，而且会很准确。

— 大卫_001
source

14

具有描述性的类，方法和变量名。这将消除对目的和描述等注释的需求。有时我们认为方法名称越短越好。相反，只要可以清楚地描述方法的目的，就可以随意命名。仅包含绝对重要的注释，并以某种特定方式帮助代码理解。更改代码时，程序员经常忘记更新注释。您最终可能会导致注释和代码不同步，并且弊大于利。

阅读Jeff Atwood撰写的这篇文章-Coding Without Comments。

— 尤索里克
source

如果可以的话，我会给这个答案+100投票。

— 克里斯·霍尔姆斯

5

我使用标准标签生成文档。仅此而已。看这里

我从来没有放过不属于课堂的信息。作者，数据，修订版是要存储在版本控制系统中的数据。

所提供的两种格式对生成文档毫无用处，并且注释方面的错误最大，它们列出了修订历史记录。

— 马尼洛
source

3

您可以通过源代码控制存储库添加许多此类信息，而实际上只留下了描述，描述应该准确地描述了类的范围和行为。我建议以Java JDK的一些Javadoc为例。

— 马丁·弗伯格（Martijn Verburg）
source

@karianna-因此，建议将除类描述之外的所有内容留给源代码控制存储库；但是，每次从存储库日志中查看它都会很麻烦。如果要创建文档文件（如.chm或sandcastle）怎么办？

— CoderHawk 2010年

@Sandy您应该能够在代码注释标题中放入某些关键字，每次您检入时，源代码控制存储库都会对其进行更新。这取决于您所使用的语言以及所使用的源代码控制库。你在用什么：）

— Martijn Verburg

@karianna-我正在使用Subversion；希望讨论一些技术/程序设计不会因此而关闭！:-)请让我知道我是否需要在SO中发布问题，询问如何将日志注释合并到特定的类？:-)

— CoderHawk 2010年

您可以使用$ Id：$和$ URL：$，：可能是可选的，我忘了。希望SO的霸主不会因为我们的亵渎而杀了我们

— 马丁·维尔伯格

3

该列表中的所有内容都是不必要的。您的源代码管理应该处理几乎所有内容，并且良好的命名约定会处理未涵盖的内容。

如果我必须阅读您的“说明”以弄清楚您的班级在做什么，那么（a）您对它的命名不佳或（b）您编写的班级不好（SRP）。

— 克里斯·福尔摩斯
source

2

我一直在尝试更改标题模板，因为正如其他人指出的那样，可以在存储库中找到很多此类信息，到目前为止，我一直希望保留的主要字段如下：

说明 -代码正在执行的操作。
注意 -关于代码的任何需要知道的内容，都不容易从代码本身的注释中得出。
引用 -尽管使用了include或类似的语句，但代码所依赖的任何引用都不清楚。

可能包含一个有用的项目是“ 关键字”一节，虽然您可以搜索函数，类，结构等名称，但文件中的某些其他名称可能不清楚。或者，对于较旧的，文档记录较差的代码，这可能是文档记录维护代码的第一步。

— 吉齐
source

1

到目前为止，我阅读的大多数其他答案都假设只有一个存储库始终可用

由于源代码可以松开与存储库的连接（即，如果已复制），则我的类文档如下所示：

class documentation header （=文件开头的注释块）仅包含必需的法律信息（即xyz在gpl-licence下的版权）
使用该类的开发人员应知道的所有内容都应放入类java-doc-comments（或等效于.net的类）中，以便现代ide-s可以将此信息显示为使用该类的工具提示信息ins源代码。

您还可以为错误修正或功能请求添加工单号，这样您可能会知道创建班级的位置/时间/原因（如果足够幸运的话，几年后仍可以访问工单）。

当beeing被要求解决旧的封闭源代码遗留程序中的问题时，票证编号对于我理解代码的原始要求非常有价值。

— k3b
source