使用版本控制时，是否有必要在每个代码文件中包含“更改日志”？

我的印象是，版本控制系统消除了将“更改日志”粘贴到代码各处的需要。我经常看到更改日志的继续使用，包括存储过程开始时的长块大块，其中很大一部分被挡住以更改文件，并用诸如此类的代码乱码：

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

和：

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

正如我向我解释的，这样做的原因是，花很长时间浏览我们的VCS日志，试图找出谁更改了内容和原因，同时将其保存在代码文件本身的顶部或附近。更改，可以轻松查看谁更改了内容和时间。尽管我明白了这一点，但似乎有些多余，只是有些“语：“嗯，我们不太了解如何正确使用VCS，因此我们根本不会理会这些东西。”

你怎么看？您是否同时使用注释和日志？只是日志？您是否发现，在代码块上方看到约翰·史密斯一周前更改了检查XYZ的方法，而不必在Diff工具中搜索日志并比较代码文件时，是否更容易编写代码？

编辑：使用SVN，但基本上只是作为存储库。没有分支，没有合并，除了日志和存储之外什么也没有。

我倾向于删除代码中的注释。我的意思是删除带有偏见。除非有注释解释为什么特定功能会执行某些操作，否则它将消失。再见。不要通过去。

因此，出于同样的原因，我也删除了这些变更日志也就不足为奇了。

注释掉的代码和读起来像书的注释的问题在于，您实际上并不真正了解它的相关性，并且使您对代码的实际作用产生了误解。

听起来您的团队在您的版本控制系统周围没有好的工具。因为您说过您正在使用Subversion，所以我想指出，有很多工具可以帮助您管理Subversion存储库。从通过网络浏览源代码的能力到将变更集链接到特定错误的能力，您可以做很多事情来减轻对这些“变更日志”的需求。

我有很多人发表评论，并说删除评论可能是错误的。我看到的已注释的绝大多数代码都是错误的代码，这些注释仅使问题变得模糊。实际上，如果我曾经注释过代码，那么可以放心，我正在向维护程序员寻求宽恕，因为我相对确定他们会杀了我。

但是，以免您认为我说过应该删除评论，这个每日WTF提交（来自我工作的代码库）完美地说明了我的观点：

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

哦，我可以告诉您有关该代码库的故事，但我会告诉您，但周围最大的政府组织之一仍在使用它。

嵌入在代码中的那些“更改日志”尤其令人讨厌。当您比较修订版时，它们只是另一个差异，而您实际上并不在乎。相信您的VCS-大多数都具有“责备”功能，它将很快告诉您谁更改了内容。

当然，真正可怕的是“旧” VCS的功能，您可以在源文件中嵌入实际的VCS日志。使得合并几乎是不可能的。

对于每个项目，我只有一个ChangeLog文件，该文件由某些提交消息自动填充。

我们没有嵌入ChangeLog注释。如果这样做，我将删除它们，并与添加它们的人进行“交谈”。我认为它们表示不了解您使用的工具，尤其是vcs。

我们提供了一种提交消息格式，可以更轻松地对日志进行grep。我们还禁止无用或含糊的提交消息。

我个人讨厌代码源文件中的更改日志。对我来说，感觉就像违反了软件工程原理，因为我所做的任何更改都必须在多个地方进行。很多时候，更改日志信息完全没有用处且不重要。以我的拙见，在您检入代码时应记录对软件的更改。

但是我知道...

我认为，如果坚持将更改日志保存在源代码中的做法，则更改日志应仅限于影响类的公共API /接口的更改。如果您在类中进行更改而不会破坏使用该更改的任何代码，那么在我看来，将这些更改记录在更改日志中只是一种混乱。但是，我可以看到有时可以方便地检查源代码文件的顶部以获取有关可能对其他任何人造成破坏的更改的文档。只是有关更改可能如何影响API以及更改原因的摘要。

另一方面，我的商店主要处理C＃内容，并且我们始终使用内联XML注释来记录我们的API，因此，阅读有关公共API更改的文档与使用intellisense差不多。

我认为坚持在源文件中添加更改日志只会给机器增加不必要的麻烦，并且首先破坏实现版本控制系统的目的之一。

我工作的最后一家公司拥有拥有17年历史，开发和年度更新的软件。并非从一个版本控制系统到下一个版本控制系统的所有迁移都会保留注释或签入注释。这些年来，所有开发人员也都没有与签到评论/注释保持任何一致性。

在源代码中带有注释的情况下，更改的考古历史记录保留为注释，而不是注释掉的代码。而且，是的，他们仍在运送VB6代码。

如果您团队中的开发人员正确使用版本控制，则可以替换代码中的更改日志注释。

如果您的团队没有在登机时添加评论或留下无用的评论，那么将来很难找到您想要的信息。

在我目前的公司中，我们需要在每次入住时提交评论。不仅如此，我们还希望在每次登机时在吉拉附带一张票。将来查看Jira时，您会看到已检入的每个文件，出现该问题的时间以及所留下的评论。非常方便。

基本上，版本控制只是一种工具，您的团队使用该工具才能提供所需的优势。团队中的每个人都需要同意如何使用它来最好地提供错误修复跟踪以及干净的代码修订版。

这是VCS日志令人困惑且VCS系统难以处理的日子（我记得那些日子，在80年代的后端）。

您的怀疑是完全正确的，这些评论更多地是障碍而不是帮助，任何现代VCS都将使您能够准确地找到所需的内容。当然，您（和您的同事）将不得不花费大约。在30-60分钟内学习如何驱动所有这些功能（我怀疑这实际上是这些注释仍然存在的原因）。

我（几乎）和乔治在一起。如果代码中的注释解释了代码本身中不立即可见的内容，则它们才是真正合理的。而且这种情况很少发生在好的代码中。如果您需要在代码中包含大量注释，那是一种气味，它会喊“重构我！”。

我们仍然将它们包括在存储过程源中，因为这样我们才能准确知道客户端上的哪个版本。该应用程序的其余部分是分布式编译的，因此我们有链接回源代码的模块版本号，但是SP作为源分发到了客户端，用于本地数据库内编译。

我们以前的PowerBuilder代码仍然使用它们，但是我认为这只是某些偷窥的舒适因素。这也将进行编译以进行分发，因此（他们应该使用IMO）使用原始的VCS历史记录。

如果您使用的是SVN，这样做会浪费时间，而且完全没有用。

SVN具有责备功能。这将准确告诉您在给定文件中每一行的创建者和时间。

变更日志注释在帮助后续开发人员提出有关新要求的更好问题时，在代码中特别有用。例如，当开发人员看到评论时，Fred将Foo字段设置为6个月前就必须满足某些要求，这表示开发人员知道在实施最新的使Foo成为可选的请求之前，他们需要提出一些问题。当您处理复杂的系统时，不同的涉众可能会具有不同的优先级和不同的愿望。更改日志注释对于记录为避免将来出现问题而做出的哪些折衷非常有用。

现在，如果每个开发人员在进行任何更改之前都检查了每一行代码的完整历史记录，那么在代码中包含这些注释将是多余的。但这从工作流程的角度来看都是不现实的-大多数开发人员只会更改验证而无需研究添加验证者的历史以及原因，从技术角度来看，版本控制系统将很难跟踪“相同的代码行（如果已从一行移到另一行或已重构为另一类）。代码中的注释更有可能被看到，更重要的是，它促使随后的开发人员注意到看似简单的更改可能并不那么简单。

话虽如此，代码中的更改日志注释应该相对较少。我不主张每次重构一点代码或修复真正的错误时都添加更改日志注释。但是，如果最初的要求是“ Foo是可选的”，并且有人来了，然后将要求更改为“为了支持下游流程Bar，则需要Foo”，这是我强烈考虑添加注释的内容。因为很可能将来的某些用户/分析师将不知道下游Bar流程，也不知道需要Foo的原因，并且会要求再次将Foo设为可选，并在Bar流程中引起麻烦。

这是在考虑组织可能会决定以某种频率更改其版本控制系统之前，尤其是当它们从具有少量开发人员的小型公司发展成为大型公司时。这些迁移通常会导致丢失更改日志注释-仅保留代码中的注释。

我很惊讶地看到没有人提到这一点，但是这不是符合许可证要求的最初原因吗？也就是说，有些许可证说您对文件所做的任何更改都必须在文件本身中注明？

我们继续在评论部分保留更改日志的原因是为了易于使用。通常，在调试问题时，滚动至文件顶部并读取更改日志要比打开源代码控制文件，定位文件中的文件并查找所做的更改要容易得多。