签入“注释过的”代码[关闭]

好的，这是导致我目前工作出现摩擦的原因，我真的没想到会发生。内部软件开发的组织是这里的一个新概念，我已经草拟了一些编码准则的初稿。

我建议永远不要将“注释掉”的代码检入到存储库中。我之所以这样说是因为该存储库保留了文件的完整历史记录。如果要删除功能代码，则将其全部删除。存储库保留您的更改，因此很容易看到更改。

这引起了一些摩擦，因为另一位开发人员认为采用此方法过于严格。该开发人员希望能够注释掉他正在处理但不完整的一些代码。这样，该代码将永远不会被签入，然后再不保存在任何地方。我们将使用TFS，因此我建议搁置更改将是最正确的解决方案。但是，由于他希望能够检入可能部署或可能未部署的部分更改，因此不被接受。

我们希望最终达到一个可以充分利用持续集成优势并自动部署到开发Web服务器的地步。当前没有Web服务器或数据库服务器的开发版本，但是所有版本都将很快更改。

无论如何，您有什么想法？您是否认为“注释掉”的代码在存储库中有用吗？

我非常有兴趣听取其他人对此主题的意见。

编辑：为清楚起见，我们不使用私有分支。如果我们这样做了，那么我会说您想用您的私有分支做什么，但是永远不要将注释掉的代码与主干或任何共享分支合并。

编辑：没有正当理由，我们不使用私人或按用户分支。这不是我不同意的概念。我们只是还没有那样设置。也许那是最终的中间立场。目前，我们使用TFS搁板。

可能会有其他人有不同的经验，但是在矿井检查中，半成品代码是一个可怕的主意。

这是我已学会并尝试遵循的原则：

• 经常检查-每天至少检查一次，但最好每天多次
• 仅签入完整功能
• 如果第一个和第二个冲突（例如，使功能正常工作需要一天以上的时间），则任务太大-将其分解为较小的可完成任务。

这表示：

• 已注释掉的代码不起作用，切勿检入
• 注释不是有效的存档策略，因此，无论是尚待完成的代码还是即将退休的代码，注释和签入都没有任何意义。

总而言之，不！如果代码还没有准备好进入下一个阶段（适合您的任何一个：IntTest / QA / UAT / PreProd / Prod），则不应将其提交到主干或多开发人员分支。期。

编辑：阅读完其他答案和评论后，我要补充一点，我认为禁止评论的代码不一定是个好主意（不确定如何实施）。我要说的是，您应该让团队中的每个人都认同我上述的哲学。我工作的团队全心全意地拥抱它。因此，源代码管理是一支无障碍的团队成员，可以帮助我们完成工作。

不接受这种哲学的人通常会导致窗户破裂，并经常受到源代码控制的挫败。他们充其量将其视为必要的罪恶，而在最坏的情况下应避免。这就导致了很少的检入，这意味着变更集非常庞大且难以合并，这会加重挫败感，使检入更多地需要避免，等等。这最终是一种态度，而不是过程。为它设置精神障碍很容易；很容易找到它为什么不起作用的原因，就像很容易找到不想节食的原因一样。但是，当人们确实愿意这样做并致力于改变其习惯时，结果将是惊人的。有效的销售是您的负担。

“从不”在指导原则中很少是一个好词。

您的同事有一个很好的例子，说明何时应该签入注释掉的代码：如果代码不完整，并且在活动状态下签入，可能会破坏应用程序。

在大多数情况下，注释掉死代码是在一个管理良好的变更控制系统不必要的。但是，并非所有注释的代码都是“死的”。

注释掉的代码永远都不要为了维护历史记录，签入。这就是源代码控制的重点。

人们在这里谈论很多理想。也许与其他所有人不同，我必须在多个项目上进行多次中断，而“现实世界”却偶尔中断了我的工作。

有时候，现实是，我必须检入部分完整的代码。这可能会丢失代码或签入不完整的代码。不管有多小，我都负担不起“完成”任务。但是，如果不输入所有代码，就不会断开笔记本电脑与网络的连接。

如有必要，我将创建自己的工作分支以提交部分更改。

我留下注释掉代码的一种情况：

// This approach doesn't work
// Blah, blah, blah

那是解决问题的明显方法，但是它包含一些细微的缺陷。当然，存储库会拥有它，但将来不会警告任何人不要走这条路。

我肯定会强烈建议不要检查已注释掉的代码。但是，我绝对不会禁止它。有时（如果很少），将注释掉的代码检入源代码管理是适当的。说“从不这样做”过于严格。

我认为我们都同意以下几点：

• 切勿将无效代码检入源代码管理
• 永远不要将损坏的（无法运行的）代码签入源代码管理中，至少永远不要将其检查到主干，也很少将其检查到私有分支YMMV
• 如果您出于调试目的暂时注释掉某些内容或破坏了某些内容，请在将代码恢复为正确格式之前不要检入代码

有些人说还有其他类别，例如临时删除的代码，或者是增量但不完整的改进，其中包括少量注释掉的代码作为后续内容的文档，或者注释的代码段很短（理想情况下为1行）输出的代码显示了永远不应该重新添加的内容。注释掉的代码应始终附有注释，说明为什么将其注释掉（而不只是删除），并给出注释掉的代码的预期寿命。例如，“以下代码弊大于利，已被注释掉，但需要在发行XXX之前替换”。

如果您要提供修补程序来阻止客户流血，并且没有立即找到最终修补程序的机会，则上述注释是适当的。交付此修复程序后，注释掉的代码提醒您仍有一些需要修复的内容。

我什么时候可以签入注释掉的代码？一个例子是，当我尝试删除某些我认为很可能在不久的将来必须以某种形式重新添加的内容时。注释掉的代码可以直接提醒您这是不完整的。当然，旧版本在源代码控制中，您可以仅使用FIXME注释作为需要更多内容的标记。但是，有时（如果不是经常的话）代码是更好的注释。

另外，当通过删除一行（或更常见的是两行）代码来修复错误时，有时我会只在注释中注释掉该行，而永远不会出于某种原因而重新启用该代码。这种评论是清晰，直接和简洁的。

Rex M说：1）仅检查完整的功能，2）[如果]任务太大，则将其分解为较小的可完成任务。

回应：是的，这是理想的选择。有时，当您在生产代码上工作时，两个选项都无法实现，并且有紧急的，关键的问题需要解决。有时要完成一项任务，您需要在字段中放置一段时间的代码版本。当您尝试查找问题的根本原因时，对于数据收集代码更改尤其如此。

对于在更笼统的问题中被问到的特定实例，只要开发人员将注释掉的代码检入一个私有分支中，除了该开发人员（可能是该开发人员正在与之合作的人）之外，没人会看到它，它没有什么危害。但是，该开发人员应该（几乎）永远不要将此类代码交付到主干或等同版本中。中继线应始终建立并且应始终起作用。将未完成的代码传递到主干几乎总是一个坏主意。如果让开发人员将未完成的代码或临时代码检查到私有分支中，则必须依靠开发人员在传送到主干之前不要忘记清理代码。

为了澄清对其他答案的评论，如果注释掉并检入了代码，我期望如果未注释掉，代码将起作用，随注释被删除的时间而下降。显然，重构工具并不总是在其重构中包含注释。几乎总是，如果我将注释掉的代码投入到生产中，则代码在那里可以用作精致的注释，比散文更具体，需要在其中完成某些工作。它不是应该长寿的东西。

最后，如果您可以在每个源文件中找到注释掉的代码，那么出问题了。出于任何原因将注释掉的代码传递到主干中应该很少见。如果这种情况经常发生，那么它将变得混乱并失去其价值。

我认为条件永远不会太强。

我倾向于将其注释掉，签入，运行测试，进行思考，然后在下一个版本之后删除注释。

通常，签入注释掉的代码是错误的，因为这会在那些不是原始作者且需要阅读或修改代码的人之间造成混乱。无论如何，三个月过去之后，原始作者通常会对代码感到困惑。

我支持这样的信念，即代码属于公司或团队，而让您的同事轻松工作是您的责任。签入注释掉的代码而没有添加任何关于为什么保留它的注释，无异于说：

我不介意您是否最终对这里的内容感到困惑。我的需求比您的需求重要，这就是为什么我要这样做。我觉得没有必要向您或其他任何人证明我这样做的理由。

对我来说，注释掉的代码通常被视为不那么体贴的同事的不尊重。

当您需要在接下来的3分钟之内添加一个小功能或类似NOW的错误修复程序，并且必须修复一个文件时，您已经开发了一半的代码。

我大体上同意不应检入注释掉的代码的原则。源代码控制系统是共享资源，并且您的同事在某种程度上将其用作他的个人便笺簿。这对其他用户不是很体贴，特别是如果您赞成共享代码库的想法。

下一个看到该注释掉的代码的开发人员将不知道这是一个正在进行的工作。他可以自由更改吗？它是死代码吗？他不知道

如果您同事的更改不在可以签入的状态，则他需要完成更改和/或学习进行较小的增量更改。

“检查可能会或可能不会部署的部分变更”-可能还意味着是否可能要进行测试？相对于非常扎实的代码库而言，这是一个滑坡。

这显示出两种思想流变的根本区别：仅检查自己满意并觉得值得保存的工作代码的人，以及检查工作以使修订控制可防止数据丢失的人。

我将后者描述为“那些喜欢将其版本控制系统用作穷人的磁带备份的人”，但这将使我不知所措。

我的猜测是您属于“良好代码”阵营，而他属于“有效代码”阵营。

[编辑]

从评论中可以，我猜对了。

正如我说的，我与您在一起，但是据我所知，这只是少数观点，无论是关于stackoverflow还是我在哪里工作。因此，我认为您不能真正将其纳入开发标准中作为唯一的操作方法。如果您仍然希望遵循标准，则不会。一个好的领导者知道的一件事就是永远不要下令他们知道不会被遵守的命令。

顺便说一句：好的编辑人员将帮助您保留旧版本。例如，在Emacs中，我将keep-old-versions和keep-old-versions设置为10，使它保留了我文件的最后10个保存。您可能会研究这种方法，以帮助您反对将版本控制作为备份的争论。但是，您永远不会赢得争论。

以我的经验，开发人员开关被注释掉了代码。

有时，新的后端是并行构建的，激活开关在源代码管理中被注释掉。

我们需要一次奇特的功能，一次却无济于事，但通常没有这种客户需要。这些东西通常会带来很高的安全性或绕过数据完整性的风险，因此我们不希望它们在开发之外活跃起来。要求开发人员首先使用它来取消注释代码，这似乎是最简单的方法。

签入注释掉的代码的另一个原因：

您正在修改现有代码，并且发现了一个细微的错误，这个错误很容易被忽略，乍一看也许看起来是正确的。对其进行注释，将其放在适当的位置，并添加注释说明正在进行的操作以及修改原因。签入，以使您对修订的评论在存储库中。

也许真正的问题是，是否应该允许开发人员签入不完整的代码？

这种做法似乎与您实现连续集成的既定目标相矛盾。

这取决于。如果出于说明目的而留在那里。在重构过程中可能很有用。否则，通常不会。同样，注释掉未完成的代码必然会导致故障和时间浪费。最好将代码分成较小的部分，并在工作时将其检入。

我的观点：如果开发人员正在自己的分支机构或沙盒区域中工作，则他们应该能够签入所需的内容。当他们将代码检入共享分支（功能分支或团队的分支，或者当然是MAIN / trunk）时，代码应尽可能原始（没有注释掉的代码，没有更多的FIXME等）。

我认为“从不”太强了。我会投票给人们是否将签入的代码签入存储库留出一些个人的余地。最终目标应该是编码人员的工作效率，而不是“原始存储库”。

为了平衡这种松懈，请确保每个人都知道注释掉的代码具有到期日期。如果注释的代码已经存在整整一周且从未处于活动状态，则任何人都可以删除它。（用适合您的感觉替换“一个星期”。）这样，您保留在看到杂物时杀死杂物的权利，而又不会直接干扰人们的个人风格。

我绝对同意不应将注释掉的代码检入到存储库中，这就是源代码控制的目的。

以我的经验，当程序员签入注释掉的代码时，是因为他（她）不确定正确的解决方案，并且更乐意将替代解决方案留在源代码中，以希望其他人做出决定。

我发现它使代码复杂并且难以阅读。

我可以签入实时系统未调用的半成品代码（这样您就可以从源代码管理中受益）没有问题。我的问题是查找没有解释的注释代码段，而造成的困境是代码被排除在外。

我认为在源代码控制系统中签入注释的代码应格外谨慎，尤其是如果用于注释代码的语言标签是由块编写的，即：

/* My commented code start here
My commented code line 1
My commented code line 2
*/

而不是基于单个行，例如：

// My commented code start here
// My commented code line 1
// My commented code line 2

（你明白了）

我要格外小心的原因是，根据技术的不同，您应该对所使用的差异/合并工具非常小心。使用特定的源代码控制系统和特定的语言，差异/合并工具很容易混淆。例如，众所周知，ClearCase的标准差异/合并对合并.xml文件不利。

如果发生注释块行合并不正确的情况，那么您的代码将在不应该合并的情况下在系统中变为活动状态。如果代码不完整并破坏了构建，那可能是最少的麻烦，因为您会立即发现它。

但是，如果代码通过了构建，则它可能在不应该存在的时候变为活动状态，并且从CM角度来看，这可能是一场噩梦。质量检查通常会测试应该存在的内容，而不会测试不应该存在的代码，因此您的代码可能会在您不知道的情况下最终投入生产，并且等到代码实现时它就会在那里不应该，维护成本增加了很多倍（因为“ bug”将在生产中或由客户发现，这是有史以来最糟糕的地方或时间）。

从理论上讲，允许源代码控制历史记录说明做某事的“旧方法”而不是注释掉该注释并检入注释是一种好主意。

但是，在现实世界中，没有人会在他们正在处理的文件上查看源代码管理历史记录，除非它是某种形式的正式审核过程的一部分（仅定期执行），或者如果某事不起作用，并且开发人员不知道为什么。

即使到那时，回首3个以上的版本基本上也不会发生。

在某种程度上，这是因为源代码控制系统无法使这种随意的审查变得容易。通常，您必须签出一个旧版本或与一个旧版本进行比较，您只会看到两个版本，而且对于更改内容并没有很好的简洁了解，因此您可以一目了然地了解更改内容。

部分是人性与团队需求的结合。如果我必须修复某些问题，并且可以在几个小时内修复它，那么我就不会花一个小时来研究一个月内没有“发布”的旧版本代码（每个开发人员都要检查通常，这意味着要进行许多修订），除非我碰巧知道其中存在某些内容（例如，如果我记得有关更改与我现在正在做的事情有关的讨论）。

如果代码被删除并重新签入，则出于所有意图和目的（除了有限的完整回滚目的），该代码将不复存在。是的，它是出于备份目的而存在的，但是如果没有人担任代码库管理员，它将会迷路。

我目前的项目中的源代码控制树大约有10个星期的历史，只有大约4名工程师组成的团队，并且大约有200个已提交的变更列表。我知道我的团队做的工作不如应做的一切准备好就立即检查。这就使得依靠阅读代码的每个部分的代码历史来捕获每个重要的更改变得非常困难。

现在，我正在初始开发模式下的项目中工作，这与维护模式下的项目有很大不同。两种环境中都使用许多相同的工具，但是需求相差很大。例如，通常存在一项任务，要求两个或多个工程师紧密合作以构建某种事物（例如某种客户端和服务器）。

如果我正在编写服务器，则可能会编写客户端将使用的草稿接口的代码，并在完全不起作用的情况下对其进行检查，以便编写客户端的工程师可以进行更新。这是因为我们的政策规定，将代码从一位工程师发送到另一位工程师的唯一方法是通过源代码控制系统。

如果任务需要花费足够长的时间，那么可能值得为我们两个人创建一个分支进行工作（尽管这违反了我组织的政策-工程师和单个团队负责人没有必要的权限源控制服务器）。最终，这是一个折衷，这就是为什么我们尝试不制定太多“始终”或“从不”政策的原因。

我可能会对这样一个没有评论的代码策略做出回应，说它有点天真。出于好意，但最终不太可能实现其目的。

尽管看到这篇文章将使我回到上周检查的代码，并删除注释的部分，该部分既不是最终的（尽管它起作用了），也不太可能再次被使用。

我认为注释掉的代码被认为是“浪费”。

我假设您在团队环境中工作。如果您自己进行工作，并且用“ todo”注释掉代码，然后您将返回到该代码，那就不一样了。但是在团队环境中，您可以放心地假设，一旦检查出注释掉的代码，该代码就会保留下来，并且很可能造成比满意更多的痛苦。

如果您正在对等代码审查，那么它可能会回答您的问题。如果另一位开发人员检查了您的代码并说“为什么此注释掉的代码试图执行'等等'”，则您的代码未通过代码检查，因此您无论如何都不应该对其进行检查。

注释掉的代码只会引起其他开发人员的问题-因此浪费时间和精力。

您需要问一个问题“ 为什么 ”代码被注释掉。一些建议：

如果您因为“不确定业务规则”而注释掉代码，那么您可能会遇到“范围蠕动”问题-最好不要用“会很高兴但我们没有时间的要求”弄脏代码库实施”-用清晰的代码保持整洁，并围绕实际内容进行测试。

如果您因为“不确定这是否是最佳方法”而将代码注释掉，那么请检查您的代码同行！时代在变化，您将看一下两年内今天编写的代码，并认为它太可怕了！但是，您无法四处注释掉您“知道”可以做得更好的部分，但现在却找不到方法。让长期维护代码库的人确定是否有更好的方法-只需编写，测试和运行代码，然后继续前进即可。

如果您因为“某些内容不起作用”而注释掉了代码，请修复它！常见的情况是“测试失败”或“待办事项”。如果有这些，则可以通过修复或摆脱它们来节省大量时间。如果可以在一段时间内“损坏”它们，则很可能会永远损坏它们。

所有这些潜在的方案（以及我在这里没有提到的方案）都浪费了时间和精力。注释掉的代码似乎似乎是个小问题，但可能表明您团队中的问题更大。

存储库是代码的备份。如果我正在编写代码，但尚未完成，为什么不注释掉并在一天结束时检入。这样，如果我的硬盘驱动器在一夜之间死了，我将不会丢失任何工作。我可以在早上取消检查代码，然后继续进行下去。

我将其注释掉的唯一原因是因为我不想破坏通宵的构建。

在1）提早检查和2）始终将存储库保持在工作状态之间，显然存在压力。如果您有多个开发人员，那么后者将具有越来越高的优先级，因为您不能让一个开发人员为自己的个人工作流程而局限在其他所有人的周围。也就是说，您不应该低估第一条准则的价值。开发人员使用各种不同的心理障碍，而个性化的工作流程是优秀的开发人员挤出多余X的一种方式。作为一名经理，您的工作不是试图去理解所有这些细微差别（除非您是天才，并且所有开发人员都是白痴，否则您都会失败），而是通过自己的决策使开发人员做到最好。

您在评论中提到您不使用私有分支。我对你的问题是为什么不呢？好的，我对TFS一无所知，所以也许有充分的理由。但是，在使用git一年之后，我不得不说，好的DVCS可以完全消除这种压力。在某些情况下，我发现注释代码在构建替换代码时很有用，但是如果我将代码强加给其他人，我会睡不着。能够在本地分支意味着我可以为我的个人进程保留有意义的提交，而不必担心（甚至通知）下游开发人员暂时的混乱。

只是呼应合唱。不惜一切代价阻止这样做。它使代码更难阅读，并使人们开始怀疑目前尚不属于应用程序的代码的优缺点。您始终可以通过比较修订来查找更改。如果进行了一些重大手术，并且在开发过程中注释掉了代码，则开发人员应该在签入/合并的修订说明中注意到它。

不完整/实验代码应在要完成的分支中。头/主干应该是始终可以编译的主线，并且是什么东西。实验分支完成/被接受后，应将其合并到总行/主线中。如果您需要支持文档，甚至还有一个IEEE标准（IEEE 1042）对此进行了描述。

我更希望看到可能无法使用的，破裂的，可访问的代码，而在同一代码上完全无法使用。由于所有版本控制软件都允许将某些“工作副本”与主干分开，因此使用这些功能确实是一个更好的主意。

可以使用新的非功能性代码在主干中，因为它是新的。它可能不会破坏任何已经起作用的东西。如果确实破坏了工作代码，那么它应该进入一个分支，以便其他开发人员可以（如果需要）将该分支检出，并查看发生了什么。

“ 疤痕组织 ”是我所说的注释代码。在版本控制系统广泛使用的前几天，Code Monkeys会将注释掉的代码保留在文件中，以防它们需要还原功能。

唯一可以签入“疤痕组织”的时间是

1. 如果您有私人分支机构，并且
2. 您没有时间使代码编译没有错误，并且
3. 你要放个长假，
4. 您不信任VCS，就像您使用Visual Source Safe OR一样。
   [编辑]
5. 如果没有留下不正确的代码作为提醒，您可能会重新引入一个细微的错误。（其他答案的好处）。

＃4几乎没有借口，因为周围有许多免费可用且功能强大的VCS系统，Git是最好的例子。

否则，只需让VCS作为您的存档和代码分发者即可。如果另一个开发人员想要查看您的代码，请给他发送差异通知，然后让他直接应用他想要的内容。无论如何，合并并不关心两个文件的编码为何不同或为何不同。

因为它是代码，所以疤痕组织甚至比写得好的注释更分散注意力。根据代码的本质，您可以使维护程序员花费大量的CPU周期来弄清楚疤痕组织是否与他的更改有关。疤痕是一周还是十年都没有关系，将疤痕组织留在代码中会给必须解密代码后缀的人带来负担。

[编辑]我要补充的是，有两种主要情况需要加以区分：

• 私人开发，编写个人项目或签入私人分支
• 维护开发，准备将签入的代码投入生产。

对疤痕组织说“不”！

我不知道- 在进行更改之前，我总是会注释掉原始行-如果我改变主意，这可以帮助我将其还原。是的，我确实将它们签入。

但是，我确实从之前的签入中删除了所有旧的注释代码。

我知道我可以查看diff日志以了解发生了什么更改，但这很痛苦-很高兴在代码中看到最后的更改。

一个不错的折衷办法是编写一个小工具，将您签出/修改过的文件转储到网络备份驱动器中。这样，您可以修改自己的内心内容并备份您的工作，但是您不必检入试验性或未完成的代码。

我认为签入注释掉的代码应该是有效的，因为新的更改已通过测试，因此查看之前的内容并查看新的更改是否确实有所改善可能会更有用。

如果我必须返回几个版本以查看以前的更改，现在该更改导致性能下降，那么这将非常烦人。

有时注释掉的代码是一个好的历史记录，但是请注明注释时间。后来，在那附近工作的人可以删除已注释掉的代码，因为事实证明它是不需要的。

知道谁注释掉了该代码也将是一件好事，这样，如果需要一些基本原理，就可以提出要求。

我更喜欢编写新功能，确保通过单元测试，将其检入，然后允许其他人使用它并查看其工作方式。

如果开发商已注释掉一些代码，因为它是尚未完成，那么正确的“源头控制”的方式来处理，这将是为开发人员，以保持它在自己的独立分支，直到该代码是准备检查在。

使用DVCS（例如git，bazaar或mercurial），这非常容易，因为不需要在中央存储库中进行任何更改。否则，也许您可​​以谈论在开发人员正在使用特定功能的情况下，在服务器上给开发人员提供自己的分支，这将花费他们足够长的时间（即几天）。

没有什么错，在某些情况下注释掉的代码检查，它只是认为这是一个情况下有可能是一个更好的方式来做到这一点，因此开发人员可以跟踪对他的来源，即使还没有准备好要检入主存储库。

显然，签入注释代码的开发人员应该在单独的分支中工作，并在必要时合并来自主干分支的更改。

由VCS系统来协助开发人员完成此工作流程（git是一个非常出色的VCS系统，可以很好地与此配合使用）。