Question

我有很多用各种语言编写的源代码文件，但没有一个在顶部有标准注释（有时甚至在同一个项目中）。其中一些根本没有任何标题评论： - ）

我一直在考虑创建一个标准模板，我可以在源文件的顶部使用，并且想知道我应该包含哪些字段。

我知道我想要包含我的名字和文件包含/做的简短描述。我还应该包括创建的日期吗？上次修改日期？上次修改文件的程序员？你发现哪些其他领域有用？

欢迎任何提示和评论。

谢谢，
卡梅伦

Answer 1

这似乎是一种垂死的做法。

StackOverflow上的一些人完全反对代码注释（推断代码应该被编写为自我解释）虽然我不会那么远，反评论人群的一些观点是有道理的，例如事实上，评论往往过时了。

评论标题块更容易受到这些症状的影响。我所在的每个组织都有这些标题块，它们已经过时了。他们有一个作家的名字甚至不在那里工作，一个完全不符合代码的描述（假设曾经做过）和最后修改日期，曾经与版本控制历史相比，似乎错过了它的最后十几个更新。

在我个人看来，请将评论贴近代码。如果您想了解代码文件的目的和/或历史记录，请使用您的版本控制系统。

Answer 2

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

我通常会说：

文件的主要目的和文件内的东西。
文件所属的项目/模块。
与文件关联的许可证（以及项目根目录中的LICENSE文件）。
谁负责该文件（团队，个人或两者）

Answer 3

您需要哪些领域？如果你不得不问是否在那里放一些信息，你真的不需要那些信息。除非你被强迫，由于你的雇主的一些官僚无能，我不明白为什么你应该去寻找比你已经觉得应该在那里更多的信息。\

Answer 4

您没有提到您使用的是版本控制系统，而您在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.

Answer 5

在大多数组织中，所有源文件都必须以合法的模糊开头。如果你真的很幸运，它只是一个单行，但在大多数情况下，它是一个非常长的法律术语块。结果，很少有人读过这些。我们的眼睛只是前往第一个程序元素，然后转到其文档。

因此，如果您想要编写任何内容，请将其与最顶层的程序元素相关联，而不是文件。

任何其他簿记信息通常应该是您的版本控制的一部分，而不是文件本身的维护（不良）。

Answer 6

除了上面的注释说明许可证，它所属的项目等，我也倾向于将“怪异”的要求放在顶部（例如“用库Y的X版本构建”）所以你或者在你没有意识到改变程序所依赖的东西之后接受它的人（或者，如果他们这样做，他们至少会知道要改变什么）

Answer 7

早在2002年，当我刚刚大学毕业，互联网泡沫破灭后，工作几乎没有，我加入了一家服务公司，该公司过去常常用Java为客户定制软件。我不得不坐在客户的办公室里（这是一个装有AC的电子分站的摇摇欲坠的房间，以保持服务器运行），与团队中的其他人共用椅子/ PC。其他工程师（如果我可以称之为工程师;）在用于对源代码进行临时更改的组中，编译文件并将其投入生产。

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

由于将文件复制到服务器的拙劣尝试导致生产服务器停机的报告（错过了要复制的文件，丢失的备份或者复制了错误的文件或者没有复制的所有文件）都遭到了耸肩（哦，不，它失败了吗？让我们看看发生了什么;嘿谁最近改变了什么...？嗯......）。

在那些日子里，在花了几个令人沮丧的日子试图弄清楚代码背后的原因和原因后，我在源文件的标题列表中设计了一个注释系统，详细说明如下：

变更日期
谁做出了改变
为何进行了更改

两个月后，当列表威胁要挑战文件中源代码的大小时，管理员明白了获得源版本控制系统。

Answer 8

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

虽然我同意许多评论，但如果您使用的是JavaDoc或其他依赖于评论的文档生成工具，那么您显然需要包含它想要查看的内容。

Answer 9

你提到的那些有用的领域是好的。谁修改了文件。

您的版本控制软件应允许在评论中嵌入关键字。例如，在CVS中，$ Id $将解析为文件，修改日期/时间以及修改文件的用户。每次办理登机手续时都会自动更新。

Answer 10

包括以下信息：

此文件的用途。这是一个非常有用的知识，它比其他任何东西都重要。您应该告诉读者，为什么有这样的文件，为什么要将函数分组到单独的文件/包/模块中以及为什么使用它们。也许是简单的，一两行，但那应该在那里。
法律事务，如果是appplicant。
保留控制台编辑器的特殊命令，例如Emacs。
添加自动记录系统所需的特殊命令。

你不应该不包含的东西是

谁创建了文件
创建时
最后一次修改了
上次修改时
最新修改添加了什么

您可以 - 并且应该 - 通过版本控制系统检索它，它会不断地自动保持最新状态。更不用说大多数这些点都没用了。

Answer 11

谁创建了文件创建时间上次是谁修改的上次修改时间最新修改添加了什么

我应该在源文件顶部的标题注释中添加什么？

11 个答案: