language-agnostic - 我应该在源文件顶部的标题注释中放什么？

Question

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

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

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

欢迎任何提示和意见。

谢谢，
卡梅伦

Answer 1

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

StackOverflow 上的一些人完全反对代码注释(理由是代码应该写成不言自明)虽然我不会走那么远，但反评论人群的一些观点是有道理的，例如评论往往会过时。

评论的标题块更容易受到这些症状的影响。我接触过的每个组织都有这些标题块，它们已经过时了。他们有一个甚至不再在那里工作的人的作者姓名，一个与代码完全不匹配的描述(假设它曾经匹配过)和最后修改日期，曾经与版本控制历史进行比较，似乎已经错过了它的最后十个更新。

在我个人看来，让注释靠近代码。如果您想了解代码文件的用途和/或历史记录，请使用您的版本控制系统。