评论已删除的代码

Question

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

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

在同行评审期间，我的开发人员小组中有人发了一条记录，说明我们应该评论要删除的代码行。我认为这是一个可怕的建议，因为它用无用的评论使代码混乱。我们哪一个是对的？

Answer 1

通常，删除的代码不应该被注释，正是因为它使代码库混乱（并且，为什么会对不存在的东西发表评论？）。

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

Answer 2

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

我有一行似乎很好且必要的代码。后来我意识到这是不必要和有害的。我没有删除该行，而是对其进行了评论，并添加了另一条评论：“下面的行是错误的，因为这样的原因”。为什么呢？

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

Answer 3

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

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

Answer 4

您应该始终删除代码。

至于能够看到旧的/删除的代码，那就是修改控制。

Answer 5

取决于删除的原因。

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

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

Answer 6

我认为它没用，并且使代码的可读性降低。想想在一些monthes之后它会是什么样的......

// 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...

你将花半个小时来了解正在发生的事情

Answer 7

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

没用吗？首先把它放在那里是错误的吗？

从我的观点来看，不需要评论。

Answer 8

作为唯一的不同意见，我会说在特殊情况下有一个评论代码的地方。有时，您将拥有继续存在的数据，这些数据通过旧代码运行，最明确的做法是将旧代码保留在源代码中。在这种情况下，我可能会留下一些注释，说明为什么旧代码只是被注释掉了。之后出现的任何程序员都能够理解仍然存在的数据，而无需在心理上检测到检查旧版本的必要性。

通常情况下，我发现代码完全令人厌恶，我经常在遇到它时将其删除。

Answer 9

我建议，是的，最好对已删除的代码进行评论，但不在代码本身。

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

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

Answer 10

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

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

Answer 11

总的来说，我倾向于非常稀疏地评论。我相信好的代码应该很容易阅读而不需要太多的评论。

我也是我的代码版本。我想我可以在过去的二十个签到中做差异，看看特定的一行是否因特定原因而改变。但这对于大多数变化来说都是浪费我的时间。

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

   // 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;

当然还出现了另一个不相关的问题，碰巧触及同一行代码，在这种情况下将其恢复到原始状态。所以新问题现在已经解决了，但旧问题突然变得重生了。 D'哦！

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

   // 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。

Answer 12

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

如果我们仍然在项目上进行大量的设计/开发，那么 在这个阶段，我通常会尝试几种不同的设计，寻找合适的方法。有时，正确的方法是我之前已经尝试过的方法。如果代码不会在源代码控制的深处丢失，那就太好了。但是一旦设计得到解决，我就会摆脱旧的代码。

Answer 13

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

Answer 14

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

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

建立一个好的版本控制系统，我认为你会发现评论变更的做法很混乱。

Answer 15

这是那些“破碎”的窗口之一，像编译器提示/警告一样没有得到解决。它会伤害你一天，它会促进团队的邋。。

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

Answer 16

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

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

无需说，我们的消息来源很快变得难以理解！维持......是一场噩梦 这就是为什么我向SciTE添加了在嵌套#ifdef / #else / #end等之间跳转的能力......在更常规的情况下它仍然有用。
后来，我写了一个Visual Studio宏，以便在我们获得VCS之后快乐地删除旧代码！

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

当然，VCS评论是最好的选择，但是当一个大文件中的更改是其他更改的几行时，引用少量删除可能很难......

Answer 17

如果您正在进行重大更改，并且需要修复现有功能，那么评论未来的代码是合理的，只要您注意到这是未来的功能，至少在我们有未来之前友好的源控制系统。

Answer 18

我将加入共识：在源代码控制存储库中删除代码被删除的原因，而不是代码。

Answer 19

我讨厌看到被注释掉的代码混乱的代码。删除代码并编写提交消息，说明删除的原因。你确实使用了源代码控制，不是吗？

请勿使用死代码丢弃活动代码。

Answer 20

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

Answer 21

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

Answer 22

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

Answer 23

我同意你的安德鲁; IMO这就是你使用版本控制的原因。通过良好的签入/提交注释和差异工具，您可以随时找到删除行的原因。

Answer 24

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

Answer 25

有一个通用的“干净代码”实践，它表示一个人应该永远不会删除已删除的代码，因为它会混乱，因为你的CVS / SVN无论如何都会归档它。

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

像这样评论代码可能是一种提供即将被删除的一般警告的方式，但当然，无法保证感兴趣的人会看到警告（尽管他们经常使用该文件） ，他们会看到它。）

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

Answer 26

我在哪里，我们将旧代码注释掉一个发布周期，然后删除注释。 （如果某些新代码存在问题且需要用旧代码替换，它会为我们提供快速修复功能。）

Answer 27

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

与所有事情一样，我认为发表声明'所有已删除的代码将始终被删除'是一种不正确的方法。

旧代码可能希望留下原因。保留代码的主要原因是，您希望将来在该部分代码中工作的任何开发人员都能看到旧代码。

依赖源跟踪显然不会给出这个。

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

- 删除旧代码，除非将其留下，提供代码中下一个开发人员需要的重要信息。即，在99％的时间内将其删除，但不要制定严格的规则，以便在情况允许的情况下删除您向下一位开发人员提供急需文档的能力。

Answer 28

我也认为这是一个可怕的建议：）

您应该使用源代码管理，如果删除某些代码，则可以在提交时添加注释。所以如果你想要的话，你还有代码历史记录......