文件中的修改历史记录

由于这些信息不会改变程序的行为,也不会使程序更容易理解,因此它不属于程序。

代码中的文档应该描述它附近的代码。如果代码更改,文档也应相应更改。版本控制系统应该负责管理更改的内容以及更改的原因。让代码及其文档完成它的工作(做事情,并描述如何/为什么做这些事情),让版本控制系统完成它的任务(控制/记录版本和更改)。

我在工作中经常看到这个问题。我目前正在开发的代码库可以追溯到1979年。你可以想象,随着时间的推移,像下面这样的评论会变得多么困难:

“下面的行似乎修复了bug xyz,如果出现不可预见的问题,将恢复”

我意识到这首先不是一个非常描述性的评论,但svn/cvs/等中的这种东西实际上非常方便。代码中这样的注释播下了怀疑的种子。评论可以删除吗?导致我不得不回头查看与此注释相关的代码的不可预见的问题是什么?等等

我只是想知道知道这个程序以前做什么有助于现在理解它?你说它有助于可读性。怎么用?

但我想谈谈“文件开始时的修改历史”。我怀疑这根本没有用。除非我想知道要比较哪个版本的文件,以查看某些“NNNN”任务引入的差异。文件开头有一行“NNNN日期-小描述”。我们的源代码管理可以“说出”这行代码是在谁和哪个版本中引入的。
因此,如果没有这一行,我会浏览所有版本以找到正确的版本。

OTOH-代码主体中描述其功能和更改者的大量注释只是噪音。

我打算亲自尝试回答这个问题。

记录源代码中的每一个更改都很难阅读,但是,如果其中有一段特别违反直觉的代码,并且是为特定的票证引入的,请在其中注明代码奇怪的原因。

/* ticket 101: add blink tag to headers, JF - 20010102 */

/* make headers blink */

很多时候,当人们停止做前一种评论时,他们会大量减少评论,这很糟糕。