我曾经在一些没有使用过源代码控制的地方工作过。他们似乎习惯于对他们改变的代码进行评论，以解释变化，以便可以恢复原状。
我发现这使得代码非常难以阅读，并且在引入源代码控制之后不太需要这样的注释，因为修订历史记录可以让您将代码与更改匹配。
但是现在，我不太确定，我认为在文件和提交消息中记录文件的主要修订可能会很好。这应该使代码更具可读性。人们是否有记录代码更改的最佳实践方法，以便它不会太混乱，但对于试图阅读它的人来说仍然是解释性的？
为了清楚起见，我不是在谈论文件头部的变化列表（这是一个完整的其他参数），而是代码中的注释。
答案 0 :(得分：5)
大多数源控制系统都有“Annotate”或“blame”命令。它显示了每个版本更改的代码。
由于此信息不会改变程序的行为，或者使程序更容易理解，因此它不属于程序。
答案 1 :(得分：3)
代码中的文档应该描述它附近的代码。如果代码更改，则文档也应相应更改。版本控制系统应该负责管理已更改的内容及其更改的原因。让代码及其文档完成它的工作（做事，描述如何/为什么要完成这些事情），并让版本控制系统完成它的工作（控制/记录版本和更改）。
无论何时开始显示当前的历史记录（当前代码），您都会遇到麻烦。如果它有很多变化，只要想想一个特别变化的代码区域会是什么样的？！
答案 2 :(得分：3)
如果评论是时间敏感的，请不要这样做，这是一个坏主意。改为在版本控制系统中对源文件发表评论。
我一直在工作中看到这个问题。我目前正在处理的代码库可以追溯到1979年。您可以想象下面那些已经建立起来的评论存在困难：
“下面的行似乎修复了xyz错误，如果发生不可预见的问题将会恢复”
我发现它首先不是一个非常具有描述性的评论，而是svn / cvs / etc中的那种东西。实际上非常方便。代码中的这样的评论播下了怀疑的种子。评论可以删除吗？难以预料的问题是否导致我不得不回顾与此评论相关的代码？等
答案 3 :(得分：2)
我只是想知道如何知道USED要做的程序有助于现在理解它？你说它有助于提高可读性。怎么样？
现在，当某些内容发生变化，因为旧的方式不起作用且新的方式是反直觉的，我认为应该在代码中进行评论，因为有必要一直都知道“这不起作用，不要再这样做。我知道它看起来更有意义。仍然不要这样做。“否则，我认为它没有帮助。
答案 4 :(得分：1)
不要认为代码中的更改是以解释的方式进行的。
但我想谈谈“文件开头的修改历史”。我怀疑这根本没用。除非我想知道要比较哪个版本的文件以查看某些“NNNN”任务引入的差异。在文件开头有一行“NNNN date - small description”。我们的源代码控制可以“说”这一行的引入者和版本 因此，如果没有这一行，我会浏览所有版本以找到正确的版本。
答案 5 :(得分：0)
我认为将主要更改或重构记录为代码中的注释是很好的。我同意阅读大量的评论确实有点混乱，但我认为忽略评论并尝试阅读代码很容易。如果有什么令人困惑的，或者你很想改变一些东西，并且附近有评论，那么你将更倾向于阅读评论，而不是使用以前的版本做差异来看看发生了什么变化以及原因。
答案 6 :(得分：0)
我们的代码库中的每个方法都有自己的更改历史记录。当方法的代码被更改时，其标头获得新条目。代码本身不会混淆历史记录，只有方法标题。每个更改历史记录条目由一行或两行组成，简要描述代码更改的一般术语的原因。该条目还包含一个引用更改文档的数字。更改文档还包含指向错误报告，开发项目，设计文档等的链接。
这些条目非常宝贵，因为它们通常可以让您深入了解代码的原因。如果您在那里修复错误，历史记录跟踪将始终告诉代码更改引入了错误，更改尝试执行的操作，以及在决定修复时需要注意的其他内容。
OTOH - 代码正文中的大量评论描述了它的作用以及何时改变了它只是噪音。
答案 7 :(得分：0)
要自己去回答这个问题。
记录源中的每个更改都会使其难以阅读，但是如果在那里有一个特别违反直觉的代码片段并且它是针对特定票据引入的，那么请记下代码为何奇怪的原因。
但代码仍应记录在案。所以当你没有放入
时/* ticket 101: add blink tag to headers, JF - 20010102 */
您可能想要放入
/* make headers blink */
很多时候，当人们停止做前一种评论时，他们会大量减少评论，这很糟糕。