Question

我工作的项目中的一些开发人员习惯于评论他们的代码以显示其添加的产品版本，例如。

// added for superEnterpriseyWonder v2.5
string superMappingTag = MakeTag(extras);
if (superMappingTag.empty())
{
     autoMapping = false;
}
// end added for superEnterpriseyWonder v2.5

每当我看到这个时，我的血压就会上升，我必须花5分钟时间浏览它才能降温。在我看来，他们不理解版本控制，如果我要使用这种做法，源文件中的每一行都将是关于何时添加内容的评论。我正在考虑从我工作的文件中删除所有这些评论，但我想知道这只是我挑剔而且这些评论实际上有什么价值吗？

Answer 1

如果您正在使用Source Control，那么我会主张在每次构建后向Source Control添加构建标签。这样，您就可以搜索针对特定构建修改的所有源代码，而没有令人讨厌的注释阻塞您的代码。

这来自清洁代码，Bob Martin的一本书：

“正确使用评论是为了弥补我们的失败我们自己的代码。请注意，我使用了字失败。我的意思是。评论是总是失败。“

当我看到评论时，我总是会想到这句话，所以我不会对你的血腥感到惊讶。

Answer 2

没有任何价值。如果您的版本控制中有一个怪工具，这将实现这一点，他们只是添加噪音。

更糟糕的是，它们会为您的代码吸引更多评论，使其完全无法读取

// added for superEnterpriseyWonder v2.5
string superMappingTag = MakeTag(extras);
if (superMappingTag.empty())
{
     // bug fix #12345674 shuld have been true
     autoMapping = true;
     // bug fix #12345674 should have been true
     i++; // v2.6 now need to up the counter DO NOT DELETE
}
// end added for superEnterpriseyWonder v2.5

然后有人会删除该方法，但将代码注释保留在

中

// added for superEnterpriseyWonder v2.5
     // bug fix #12345674 should have been true
     // v2.6 now need to up the counter DO NOT DELETE
// end added for superEnterpriseyWonder v2.5

对糟糕的评论说不。

Answer 3

我认为没有价值：也可以使用SCM的注释/指责功能检索此信息。此外，任何人都可以在这些评论之间添加文本，这使得评论过时了（因为你可能会为v2.6添加一些内容，而评论会说v2.5）

另外需要注意的是，这些注释本质上是隐藏的：只有当您查看相关源代码时才能看到它们，因此您无法使用它来生成更改日志或其他内容。

Answer 4

如图所示的评论可能没有用。但是，有时添加功能可能会导致添加不那么明显的代码。在这种情况下，描述变更的注释和/或代码不明显的原因是合适的。

Answer 5

这里不仅没有价值......还有负值。在大多数地方，评论的维护已经很粗略，这只会让人们更加难以理解。这些评论对读者没有任何价值，因此当他们在他们的记忆中有另一行代码时，他们会用无用的版本信息堵塞他们的大脑。这也是合并冲突的另一条线（完全不是在这里开玩笑......我在评论中看到了合并冲突）。

Answer 6

在某些情况下可能有用（例如，如果这有助于理解为什么某些函数在V3中的工作方式与在V2中的工作方式不同），但一般情况下，SCM的工作就是知道何时添加了什么。

Answer 7

你不挑剔恕我直言。至少有三个很好的理由不在源代码中添加这种类型的注释：

他们的位置实际上是在版本控制系统中，您可以在其中拥有已更改的所有内容的全局视图，以适应新版本的库或新功能。如果正确完成并且使用了日志。
如果源代码是客户可交付成果的一部分，也许他们不需要知道发生了什么的历史。想象一下，你已经为另一个客户做了修改，并把它放在评论中！
太多的评论并不比太少好。

但这条线不清楚，

之间会有什么区别

// Compliance with specs abc (additional xyz feature)
...
... // some code

和

// xyz feature:
...
... // some code

一般而言，我不会在源代码中添加与历史相关的任何内容，但坚持评论已完成的工作，如何完成，以便其他人可以轻松浏览代码并理解它。

我的建议：编写方法文件或进行非正式讨论。

Answer 8

如果看到超级评论使你的血压升高，你需要喝酒或其他什么。

那就是说，我同意这些评论大多没用。如果一直使用，该计划很快就会成为这种评论的迷宫。如果一行为版本2.5更改一次然后一年后再次更改为错误3294怎么办？你把两个“版本”评论放在同一行，还是只保留最新的？如果你只保留最新的，那么你已经失去了最初为2.5添加的事实。如果你同时保留它们，当第三次改变或第四次改变时会发生什么？我们如何知道每次变化后的状态？在版本2.5中添加代码块后会发生什么，然后在版本2.6中添加嵌入在2.5块中的另一块代码？等等。程序很容易得到比代码行更多的版本注释。

如果不能始终如一地进行，评论很快就会产生误导。有人可以发表评论说这个块是为2.5添加的，其他人可以在2.6版本的区块内插入代码而不评论它，现在我们有一个评论似乎说第二个块是为2.5添加的。

我们关心那么多吗？在做出改变时，我很少关心。哦，好几个星期前，我很关心，因为我想知道谁应该为一个主要的搞砸而责备。

正如其他人所指出的那样，版本控制系统会在您需要的时候为您执行此操作。我想如果你没有任何类型的VCS，可以做一个案例。但是你可以免费获得一些非常好的VCS。如果你需要一个，那就买一个。否则你就像那些说你应该练习算术的人，否则如果你的计算器退出工作你会怎么做。这个假设显然是在任何时刻，世界上所有的计算器都可能同时崩溃。

你可能会说，它可以帮助说，“哦，这被添加到订单输入以支持新的销售员时间卡功能”或其他一些。但重要的是这不是“这个代码被Bob改为版本3.2.4”，而是“这个代码产生的数据在这里没有使用，但是那边的另一个模块需要”。

我坚信编写评论，介绍代码部分并描述复杂或非显而易见代码背后的一般概念。但那是完全不同的事情。

Answer 9

考虑一些人可能必须从VCS获取快照。在这种情况下，他们没有历史可以依赖...而且这样的评论变得有用。

Answer 10

我看到很多代码编写的代码直到最近才使用版本控制。我猜他们只是习惯了，现在很难停下来。

我发现的另一个原因是，有时候知道哪些代码与哪个版本相关是很重要的。当然你总是可以检查版本日志，但你并不总是有时间，这很烦人。在某些情况下，“代码为v3.2”比其他开发人员更多地说“代码来做x，y和z”......这一切都取决于团队建立的约定。

另一个答案是，在某些项目中我使用了一些代码进行了类似的评论，但是在项目实际开始使用版本控制之前。在这种情况下，保持这种方式也是有意义的。

Answer 11

我发现它们很有用，它可以节省追逐VCS的速度，找出为什么要对代码进行更改，或找到BugId来查找缺陷，因为我记得代码更改的内容。

虽然理论上VCS包含信息，但实际上它可能会被掩埋，特别是通过集成。

在其他更容易的作品中：

// DEF43562 - changed default value
foobar = true

或者

责备（或等同）
追逐历史找到正确的变化。
关注整合到源，和重复1＆amp; 2。
查找附加的错误ID 原来的改变，如果你是幸运的。

基本上，评论是围绕VCS的一个捷径，以及片状的VCS / BugTracking集成。

我发现这些评论也可用作以下标记：“此决定已由客户/用户/审核委员会审核，这是选定的答案，请注意更改行为”。

评论是否显示添加/修改了哪些版本代码有用？

11 个答案: