34

评论被删除的代码是一个好习惯吗？例如：

// Code to do {task} was removed by Ajahn on 10/10/08 because {reason}.

在同行评审期间，我的开发人员组中的某个人注意到我们应该评论要删除的代码行。我认为这是一个糟糕的建议，因为它用无用的注释使代码混乱。我们谁是对的？

4

28 回答 28

106

一般来说，被删除的代码不应该被评论，正是因为它使代码库变得混乱（而且，为什么要评论一些不存在的东西？）。

您的缺陷跟踪系统或源代码控制管理工具是此类评论所属的地方。

于 2008-11-11T15:24:59.590 回答
29

当注释掉代码（而不是删除）是一个好主意时，有一些（罕见的）情况。这是一个。

我有一行看起来不错且必要的代码。后来我意识到这是不必要的和有害的。我没有删除该行，而是将其注释掉，并添加了另一条评论：“由于某些原因，下面的行是错误的”。为什么？

因为我相信下一个代码读者会首先认为没有这一行是一个错误，并会尝试将其添加回来。（即使读者是两年后的我。）我不希望他先咨询源代码控制。我需要添加评论以警告他这种棘手的情况；并且有错误的线路以及错误的原因恰好是最好的方法。

于 2008-11-11T16:55:25.100 回答
14

我同意在评论中删除代码不是一个好主意。

应通过版本控制系统查看代码历史记录，在这里可以找到旧代码以及删除它的原因。

于 2008-11-11T15:25:08.013 回答
8

您应该始终删除代码。

至于能够看到旧的/删除的代码，这就是版本控制。

于 2008-11-11T15:25:47.433 回答
6

取决于删除的原因。

我认为注释是对未来维护代码的人的提示，如果代码存在但被删除的信息对维护代码的人有帮助（可能是“不要那样做”的标志），那么它应该在那里。

否则，在每个代码更改上添加带有名称和日期的详细注释只会使整个事情变得不可读。

于 2008-11-11T15:27:12.720 回答
4

我认为它非常没用，并且使代码的可读性降低。想想几个月后会是什么样子......

// removed because of this and that
/* 
      removed this stuff because my left leg...
*/
 doSomething();
// this piece of has been removed, we don't need it...

你会花半个小时来了解发生了什么

于 2008-11-11T15:27:41.330 回答
3

问题是，为什么要删除代码？

没用吗？一开始就把它放在那里是错误的吗？

从我的角度来看，不需要评论。

于 2008-11-11T15:25:00.353 回答
2

它在调试时很有用，但没有理由以这种方式签入代码。源代码控制的重点是能够恢复旧版本，而不会用注释掉的代码弄乱代码。

于 2008-11-11T15:25:16.000 回答
2

我建议，是的，对已删除但不在代码本身中的代码进行评论是一种很好的做法。

为了进一步阐明这一立场，您应该使用允许某种形式的签入注释的源代码控制系统 (SCCS)。那是你应该放置关于为什么代码被删除的注释的地方。SCCS 将提供代码发生情况的完整上下文历史记录，包括已删除的内容。通过添加签入评论，您可以进一步阐明该历史记录。

直接在代码中添加注释只会导致混乱。

于 2008-11-11T15:26:43.313 回答
2

最近的共识（来自这里的其他讨论）是应该删除代码。

我个人会注释掉代码并用日期或原因标记它。如果它是旧的/陈旧的并且我正在通过文件，那么我将其删除。版本控制使返回变得容易，但不像取消注释那么容易......

于 2008-11-11T15:26:46.917 回答
2

听起来您正试图绕过对代码进行版本控制。从理论上讲，这听起来是个好主意，但在实践中，它很快就会变得非常混乱。

我强烈建议将代码注释掉以进行调试或运行其他测试，但在做出最终决定后将其从文件中完全删除！

获得一个好的版本控制系统，我想你会发现注释掉更改的做法很混乱。

于 2008-11-11T15:28:38.990 回答
2

这里没有人写过很多关于为什么你不应该留下注释掉的代码，除了它看起来很乱。我认为最大的原因是代码可能会停止工作。没有人在编译它。没有人通过单元测试来运行它。当人们重构代码的其余部分时，他们并没有重构它。很快，它就会变得毫无用处。或者比无用更糟糕——有人可能会取消注释，盲目地相信它有效。

如果我们仍在对项目进行繁重的设计/开发，有时我会注释掉代码。在这个阶段，我通常会尝试几种不同的设计，寻找正确的方法。有时正确的方法是我之前已经尝试过的方法。因此，如果该代码不会在源代码控制的深处丢失，那就太好了。但是一旦设计完成，我就会摆脱旧代码。

于 2008-11-11T16:57:47.000 回答
2

一般来说，我倾向于很少评论。我相信好的代码应该易于阅读，无需太多评论。

我还对我的代码进行了版本控制。我想我可以对过去 20 次签入进行比较，以查看特定行是否因特定原因而更改。但是对于大多数更改，这将浪费我的时间。

所以我尝试巧妙地评论我的代码。如果出于相当明显的原因删除了某些代码，我不会费心评论删除。但是，如果由于某种微妙的原因而删除了一段代码（例如，它执行了一个现在由不同线程处理的函数），我将注释掉或删除代码并添加横幅注释原因：

   // this is now handled by the heartbeat thread
   // m_data.resort(m_ascending);

或者：

   // don't re-sort here, as it is now handled by the heartbeat thread

就在上个月，我遇到了一段我在一年前为了解决一个特定问题而更改的代码，但没有添加解释原因的注释。这是原始代码：

   cutoff = m_previous_cutofftime;

这是代码，因为它最初被修复为在恢复中断状态时使用正确的截止时间：

   cutoff = (!ok_during) ? m_previous_cutofftime : 0;

当然，另一个不相关的问题出现了，它碰巧触及了同一行代码，在这种情况下将它恢复到原来的状态。所以现在新问题已经修复，但旧问题突然被重新破解。哦！

所以现在签入的代码如下所示：

   // this works for overlong events but not resuming
// cutoff = m_previous_cutofftime;
   // this works for resuming but not overlong events
// cutoff = (!ok_during) ? m_previous_cutofftime : 0;
   // this works for both
   cutoff = (!resuming || !ok_during) ? m_previous_cutofftime : 0;

当然，YMMV。

于 2008-11-11T17:21:31.133 回答
2

作为唯一的反对声音，我会说在特殊情况下有一个注释掉代码的地方。有时，您将拥有通过旧代码运行的继续存在的数据，最明确的做法是将旧代码保留在源代码中。在这种情况下，我可能会留下一点说明，说明为什么旧代码被简单地注释掉了。任何后来出现的程序员都能够理解仍然存在的数据，而不必从心理上检测是否需要检查旧版本。

不过，通常情况下，我发现注释掉的代码完全令人讨厌，我经常在遇到它时将其删除。

于 2008-11-11T18:49:33.233 回答
1

如果您要删除代码。你不应该评论你删除它。这是源代码控制的全部目的（您正在使用源代码控制？对吗？），正如您所说的那样，注释只会使代码混乱。

于 2008-11-11T15:26:11.273 回答
1

我同意这是一个糟糕的建议。这就是为什么您拥有具有修订版的源代码控制。如果您需要返回并查看两个修订版之间的更改，请区分这两个修订版。

于 2008-11-11T15:26:18.853 回答
1

我讨厌看到代码被注释掉的代码弄得乱七八糟。删除代码并写一条提交消息，说明它被删除的原因。你确实使用源代码控制，不是吗？

不要用死代码乱扔活动代码。

于 2008-11-11T15:27:10.427 回答
1

我将在共识中加入我的声音：将关于为什么删除代码的评论放在源代码控制存储库中，而不是在代码中。

于 2008-11-11T15:27:13.283 回答
1

这是诸如编译器提示/警告未解决的“损坏”窗口之一。它总有一天会伤害你，它会促进团队的马虎。

版本控制中的签入注释可以跟踪删除此代码的内容/原因 - 如果开发人员没有留下注释，则跟踪它们并限制它们。

于 2008-11-11T17:53:16.903 回答
1

一个小轶事，为了好玩：几年前我在一家公司，对源代码版本控制一无所知（他们后来得到了这样的工具......）。
因此，在我们的 C 源代码中，他们有一条规则：“当您进行更改时，请使用预处理器宏禁用旧代码”：

#ifdef OLD /* PL - 11/10/1989 */
void Buggy()
{
// ...
}
#else
void Good()
{
// ...
}
#end

不用说，我们的资源很快变得难以阅读！维护是一场噩梦......
这就是为什么我在 SciTE 中添加了在嵌套的 #ifdef / #else / #end 等之间跳转的能力......它在更常见的情况下仍然有用。
后来，我写了一个 Visual Studio 宏来愉快地摆脱旧代码，一旦我们得到了我们的 VCS！

现在，就像 buti-oxa 一样，有时我觉得有必要说明为什么我删除了一些代码。出于同样的原因，或者因为我删除了我认为不再需要的旧代码，但我不太确定（遗留、遗留......）。显然不是在所有情况下！
实际上，我不会留下这样的评论，但我能理解这种需要。
更糟糕的是，我会在一个版本中注释掉，并在下一个版本中删除所有内容......
在我目前的工作中，对于重要的本地更改，我们保留旧代码但可以通过属性重新激活它，以防万一。在生产中测试了一段时间后，我们最终删除了旧代码。

当然，VCS 注释是最好的选择，但是当更改是大文件中的几行以及其他更改时，引用小删除可能会很困难......

于 2008-11-25T15:08:13.590 回答
1

如果您正在进行重大更改，并且需要对现有功能进行修复，那么注释掉未来的代码是合理的做法，前提是您指出这是未来的功能，至少在我们拥有对未来友好的源代码控制之前系统。

于 2008-12-02T12:24:22.827 回答
0

我也认为这是一个糟糕的建议:)

您应该使用源代码控制，如果您删除了一些代码，您可以在提交时添加注释。因此，如果您愿意，您仍然拥有代码历史记录...

于 2008-11-11T15:26:07.310 回答
0

我评论未使用的代码是因为你永远不知道什么时候必须回退到古老的代码，也许旧代码会帮助其他人理解它，如果它当时更简单的话。

于 2008-11-11T15:26:59.883 回答
0

我同意你的看法，安德鲁；IMO 这就是您使用版本控制的原因。通过良好的签入/提交评论和差异工具，您总能找出删除行的原因。

于 2008-11-11T15:27:17.947 回答
0

如果您使用任何形式的源代码管理，那么这种方法有些多余（只要使用描述性日志消息）

于 2008-11-11T15:27:37.120 回答
0

有一种通用的“干净代码”实践表明，永远不要将已删除的代码保留为注释掉的代码，因为它很混乱，而且您的 CVS/SVN 无论如何都会将其存档。

虽然我确实同意这一原则，但我不认为它是适用于所有开发情况的可接受方法。根据我的经验，很少有人会跟踪代码中的所有更改和每次签入。因此，如果没有注释掉的代码，他们可能永远不会意识到它曾经存在过。

像这样将代码注释掉可能是提供即将被删除的一般警告的一种方式，但是当然，不能保证感兴趣的各方会看到该警告（尽管如果他们经常使用该文件，他们会看见）。

我个人认为正确的方法是将代码分解到另一个私有方法中，然后联系相关利益相关者并在实际摆脱该功能之前通知他们待删除的内容。

于 2008-11-11T18:54:31.943 回答
0

在我所在的位置，我们在一个发布周期内注释掉旧代码，然后在此之后删除注释。（如果某些新代码有问题并且需要用旧代码替换，它可以让我们快速修复。）

于 2008-11-11T22:20:47.270 回答
0

在几乎所有情况下，旧代码当然应该在您的 RCS 中删除和跟踪。

就像所有事情一样，我认为声明“所有已删除的代码将始终被删除”是一种不正确的方法。

出于多种原因，可能需要保留旧代码。保留代码的主要原因是当您希望将来在该部分代码中工作的任何开发人员看到旧代码时。

依靠源跟踪显然不能做到这一点。

所以，我相信正确的答案是：

- 删除旧代码，除非留下它提供代码中的下一个开发人员需要的关键信息。即，在 99% 的情况下将其删除，但不要制定一项严厉的规则，即当情况需要时，您将无法向下一个开发人员提供急需的文档。

于 2008-11-25T15:29:48.867 回答