我应该在源文件顶部的标题注释中放些什么?

创建日期、修改日期和上次更改文件的作者应存储在源代码管理软件中。

我通常把:

• 文件的主要用途和文件中的内容。
• 文件所属的项目/模块。
• 与文件关联的许可证(以及项目根目录中的许可证文件)。
• 谁负责文件(团队、人员或两者)

这似乎是一种垂死的习惯。

StackOverflow上的一些人完全反对代码注释(理由是代码应该被编写成不言自明的代码),而我不会这么做,反注释人群的一些观点是有意义的,例如注释往往过时。

标题栏的注释更容易受到这些症状的影响。我去过的每个组织都有这些标题栏,它们已经过时了。他们有一个作者的名字,一个甚至不再在那里工作的人,一个完全不匹配代码的描述(假设它曾经做过),和上次修改的日期,这一次与版本控制历史相比,似乎错过了它的最后十几个更新。

在我个人看来,把评论放在代码附近。如果您想知道代码文件的用途和/或历史,请使用版本控制系统。

您需要哪些字段?如果你不得不问是否要在那里放一些信息,你并不真正需要这些信息。除非你被雇主的官僚无能所逼,否则我不明白你为什么要去寻找比你认为应该去的更多的信息。\

在大多数组织中,所有源文件都必须以合法的Blurb开头。如果你真的很幸运,它只是一条直线,但在大多数情况下,它是一个很长的法律街区。因此,很少有人读过这些书。我们的眼睛只需移动到第一个程序元素,然后查看它的文档。

因此,如果您想写任何东西,请结合最顶层的程序元素来写,而不是文件。

任何其他簿记信息通常都应该是版本控制的一部分,而不是在文件本身中维护(糟糕)。

除了上面提到的关于许可证、它所属的项目等的评论之外,我也倾向于把“奇怪”的需求放在最前面(比如“用库Y的X版本构建”),所以你或者在你改变程序所依赖的东西而没有意识到它的人(或者,如果他们这样做的话,他们至少会知道要改回什么)

回到2002,当我大学毕业,工作岗位很少,在网络泡沫破裂之后,我加入了一个服务公司,用来创建在Java中为他们的客户定制的软件。我不得不坐在一个客户的办公室里(这是一个安装了空调的电力分站里摇摇欲坠的房间,以保持服务器的运行),和团队中的其他人共享椅子/个人电脑。组中的其他工程师(如果我可以叫他们工程师;)用于对源代码进行临时更改、编译文件并将其投入生产。

• 不知道是谁做出了什么改变。
• 没办法弄清楚为什么要做任何改变。
• 除非工程师“记住”他所修改的内容,否则无法转到以前版本的代码。
• 备份:从生产服务器复制文件,这些文件已替换为新文件。
• 备份位置:工程师将文件复制到生产服务器的主目录。

由于尝试将文件复制到服务器时出错(丢失了要复制的文件,备份丢失或复制了错误的文件,或者没有复制所有文件),生产服务器出现故障的报告都会耸耸肩(噢,不,是否已关闭?让我们看看发生了什么;嘿,谁最近改变了什么…?嗯……)。

在那些日子里,在花了好几天时间试图找出代码背后的原因和原因之后,我设计了一个系统,用于在源文件标题中的一个列表中添加注释,其中详细说明了以下内容:

1. 变更日期
2. 是谁做的改变
3. 为什么要改变

两个月后,当列表威胁要挑战文件中源代码的大小时,管理者想出了一个聪明的主意,那就是获得一个源版本控制系统。

我从没有必要在我工作过的任何公司的源文件头(除了版权声明)中添加任何评论。在我目前的公司中,通过查看代码,或者访问与源版本控制系统集成的bug报告系统,其他一切都是不言而喻的。

很大程度上取决于您是否使用自动文档生成工具。

虽然我同意许多评论,但是如果您使用的是JavaDoc或其他一些依赖于评论的文档生成工具,那么您显然需要包括它希望看到的内容。

您没有提到您使用的是版本控制系统,Neil N回答中的评论证实了这一点。虽然使用版本控制是最好的方法,但我也经历过许多这样做的成本在旧代码上不会由项目发起人支付的情况。如果您没有项目的集中更改历史记录,那么可以将更改历史记录放入模块中。对于新代码,使用版本控制系统是很好的。

Your company name
All rights reserved (c) year - or reference to appropriate license

Project or library this file is for

Module it belongs to

Description of what it contains

History
-------
01/08/2010 - Programmer - version
  Initial creation.  
01/09/2010 - Programmer - version
  Change description.
01/10/2010 - Programmer - version
  Change description.

你提到的那些有用的领域是好的。修改文件的人和时间。

您的版本控制软件应该允许在注释中嵌入关键字。例如,在cvs中,$id$将解析为文件、修改日期/时间以及修改文件的用户。每次入住都会自动更新。

包括以下信息:

• 这个文件是用来做什么的 . 这是一个非常有用的知识,比任何其他知识都重要。你应该告诉读者,为什么会有这样一个文件,为什么你把函数分组在一个单独的文件/包/模块中,以及为什么要使用它们。可能是简短的,一行或两行,但应该在那里。
• 法律材料 ,如果适用。
• 为控制台编辑器(如Emacs)的特殊命令离开该位置。
• 添加自动文档系统所需的特殊命令。

你应该做的事 不 包括

• 文件的创建者
• 当它被创建时
• 上次修改它的人
• 上次修改时
• 最新修改添加了什么

您可以——而且应该——通过版本控制系统来检索它,在那里它可以不断地并且自动地保持最新状态。更不用说这些要点中的大部分都是无用的。