为什么注释掉代码然后逐渐删除代码以跟踪我已经完成的工作以及还有什么工作呢?

每当我发现我的代码的很大一部分需要被更改时,要么是因为它不正确,要么是因为它需要适应其他原因所需的主要体系结构更改,这就是我通常所做的:

  1. 我注释掉了我怀疑可能需要更改的所有代码。我将注释掉的代码视为我的TODO列表。
  2. 我逐渐检查注释掉的代码并取消注释此代码的部分内容,或者将它们复制粘贴到别处,然后根据需要进行编辑,或者从头开始重写部分代码,查看注释掉的代码以供参考。每当我想到我已经完成了部分已注释掉的代码时,我就将其删除。
  3. 我继续这个,直到我看不到更多注释掉的代码。

我应该注意到,我主要是在我独自开发的个人项目中做这件事。

然而,有人告诉我,我应该停止这样做。我被告知相反,我应该开始使用git,引用旧提交来查看旧代码,而不是留下注释掉的代码。有人告诉我:

评论代码是一种应该被消灭的坏习惯。你缺乏经验,所以你不理解。如果在几年后,你看到另一个喜欢评论代码的人的代码,那么你自己就会开始咒骂这个人。每当我看到注释掉的代码时,我都会将其全部删除,甚至不用看它,因为通常这样的代码完全没用。您肯定无法看到在小型单人项目中评论代码的缺点;但如果你找到一份工作并保持这种习惯,那将是一种耻辱。

我可以问一下,我正在做的事情的这些缺点是什么,我现在没有看到?

我必须说我并不热衷于只使用git来查看过去的代码。正如我所说,我将代码注释为一种todo-list;虽然git会告诉我代码是如何看的,但是它无法清楚地告诉我哪些代码部分仍然需要被审查以及哪些代码已经完成。我担心我可能会错过部分代码并引入错误。

为了完整起见,我觉得我应该补充一点,我所引用的人是一位经验丰富的开发人员,也是鲍勃叔叔的“清洁代码”的粉丝 - 鲍勃叔叔确实批评在他的书中严厉地评论代码。

18
@Goyo我根本没有使用版本控制。我被告知我绝对应该开始使用版本控制(即使它是一个人的个人项目),其中,版本控制将允许我停止评论代码(我应该)。
额外 作者 baron,
@Goyo如果我在我的分支上这样做有害吗?
额外 作者 baron,
@gaazkam在这里阅读: git for personal(one-man)projects 。矫枉过正?我自己的两分钱:在评论代码方面,你的目标是什么并没有错。但是编写没有源代码控制的项目是一个严重的错误。 Git是免费的,快速的,低维护的。没有充分的理由通过不使用它或其他源控制系统来危害您的代码库。
额外 作者 hao,
等等,你写道你有一个足够大的代码库,有时“需要适应主要的架构变化” - 你当前没有使用版本控制? WTF - 认真吗?你在开玩笑,不是吗?如果确实如此,那么问题就是问题,如果你使用经过评估的代码的方式是否正常。
额外 作者 Peter LeFanu Lumsdaine,
用30多种语言编写了30多种语言,我发现自己犯了错误。当一行代码不能正常工作时,我会复制并注释掉其中一个代码。然后进行更改,然后重试。如果代码,我最后会看到该行的历史记录。最终可以删除较旧的注释掉的行,但我始终至少保留最新的行,因为活动代码可能会变得无法正常工作,而使用tweek的旧方法更好。继续做你正在做的事情。忽略“专家”。
额外 作者 yaplik,
确实,如果您使用代码,您可以通过取消注释来轻松撤消代码,但是如果您在相当多的文件中更改了ssome并且需要返回,那么在没有版本控制的情况下,您会非常紧张。因此,“开始使用源代码控制”应优先于“不注释代码”:)
额外 作者 Walfrat,
额外 作者 Michael H.,
您是否将注释代码提交给版本控制?
额外 作者 Goyo,
它不会,但这不是我的观点。如果你找到一份工作并继续做你正在做的事情,当你的队友从版本控制中检出代码时,他们会在那里看到你的评论代码吗?
额外 作者 Goyo,
如果在合并之后(并且你可以这样做)谁会受伤?在主分支中看不到注释的代码?如果你觉得需要在删除已经注释掉的代码之前提交,这些代码暗示你可能会采取太大的步骤,但这是另一回事。
额外 作者 Goyo,

6 答案

如果你最终删除所有已注释掉的代码,我认为没有真正的问题。在代码库中留下注释代码是一种不好的做法,但如果你完成所有工作并消除它,那就不是你正在做的事情。我怀疑你正在与之交谈的人要么不理解你正在使用的过程,要么就是教条。

实际上,评论代码是无害的。问题是它很乱并且难以阅读。有更糟糕的罪恶,但消除这是一件非常简单的事情。作为评论代码的人,您最有可能确定它可以被完全删除。

很多IDE和代码编辑都在评论中理解某种“TODO”语法。这是标记需要更改的内容的另一种方法。您可能需要考虑这一点,因为它会在您标记时提供有关您的想法的更多信息。

在一天结束时,做一些事情会为您带来最佳结果。即使这是一个团队项目,只要你删除所有注释代码,你就不会给其他任何人带来负担。

23
额外
我有几个代码库,我的工作充满了 TODO 评论。说实话,它并不是那么糟糕,因为它通常是1-2行。关于 TODO 评论我喜欢的事情是我的IDE在终端附近有一个“TODO”标签,自动填充该评论列表,并预览评论和文件/行号。重点是,在特定的公司中,即使他们使用Git/Github,他们也不会喘息使用问题。是的,你能做些什么,试着说服管理层使用Git Issues而不是Google Sheets?是的,尝试过但都失败了。那好吧。 TODO评论它!
额外 作者 xandy,
@PeterM这里的要点是只要你摆脱它就没关系。您不应该在代码库中留下注释代码。我在重构时经常做的就是注释掉变量,看看创建了多少错误,以帮助我理解它将会有多少工作。根据我打算做什么,我可能会这样做,直到我解决了所有这些问题,然后通过删除注释代码来完成更改。
额外 作者 JimmyJames,
我不记得我听到了什么,但有一个论点,一般来说,注释掉的代码并不是无害的,因为它永远不会被重构。请注意,这预先假定您最终将取消注释并重新使用该代码块。
额外 作者 Peter M,

我可以问一下,我正在做的事情的这些缺点是什么,我现在没有看到?

可以说,如果你单独工作并且不使用版本控制并且觉得可以这样做就可以了。

事实上,如果没有版本控制,那么在“时间”中的任何时候你做什么并不重要,因为代码总是在操作系统中“保存”当前文件的状态。

如果您使用版本控制,并且您有大量注释作为“待办事项列表”,并且您修复了一些并删除了注释,那么重复,然后重复等等...然后您将“正在进行中”代码并保存注释在您的修订历史中。如果您以后永远不需要回滚到另一个提交或甚至“樱桃选择”(例如,您在此处进行特定提交并将其拉入另一个分支以供使用),这将不会成为问题。但否则可能会出现问题。

可以说,这可以与硬盘驱动器软件“快照”相比,就像Windows一样(恢复的东西)。如果它带有病毒的快照,你会杀死病毒,但后来需要回滚,你可以回到病毒再次出现的地方。

当您使用版本控制与其他开发人员合作时,此方法也可能可能,因为他们必须查看您的待办事项列表这对他们没用。事实上,他们不得不忽视和解决这个问题。在我们的团队中,我们总是删除所有评论,例如旧代码或“备注”。除非它们有用 - 但这是非常罕见的,因为我们有“如何工作”的文档,以及用于跟踪需要完成的工作的软件(aka todo)。

此外,在处理大型项目时,您倾向于协作,并经常提交和推送,因此,如果他们将您的分支合并到他们的分支中,他们正在处理的分支可能有您的TODO列表。那么你的TODO清单就是每个人的事:D

总而言之,如果你不单独工作,特别是在使用版本控制时,它会使历史变得混乱,并且可能会混淆其他开发人员。

并且,这在某些方面是个人的事情,但使用代码库作为你的“待办事项列表”并不理想。有一天,你可能会意外地留下一些东西,或忘记评论或错误地取消注释。


与许多架构,编码方法以及您个人或团队的工作方式一样,每个场景都可以调用不同的东西。因此,请考虑提到的缺点,以及使用版本控制的好处,并确定它是否适用于

5
额外
这就是您处理功能分支并使用压缩合并的原因。其他开发人员永远不应该看到正在进行中的代码,因此使用什么方法来开发代码并不重要。
额外 作者 Jules,

这听起来像你的评论家有点教条。我不确定发誓某人评论代码是PC ;-),甚至是有帮助的;-)

但更严重的是,我认为你的评论者是对的,你应该认真考虑使用git(或其他一些源代码控制系统,但git是一个明智的选择)。

这样做可能会减轻您注释代码的一些需求。

但是在代码中有一个TODO列表(无论是项目符号列表还是旧代码) - 在我看来是非常合理的。但是你可能想重新考虑一下你是如何做到这一点的。首先,我建议考虑别人阅读你的代码。在你放弃并重新加入项目一年后,别人可能成为你。或者它可能完全是其他人。只是遇到注释掉的代码有点令人困惑。也许是这样的:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

就个人而言,我更倾向于这样的事情:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

我可以随意从旧代码中输入“代码片段”作为帮助。

使用git很难(遗憾)。这将花费你一段时间来学习,它可能感觉它不是你想要完成的一部分。但是如果你打算有用地编程,你将需要学习如何作为团队的一部分,并与团队沟通,而git就是现在如何做到的。一旦你开始使用它,你会发现它是一个非常有用的工具/拐杖,使你的软件开发更容易。

祝你好运!

4
额外

评论代码有很多理由: -

  • 现在还不对,你准备好之后就不会发表评论。
  • 您正在临时评论它以在调试时更改行为。
  • 您不确定是否需要该代码,但在您进行了更多测试之前不想删除它。
  • 某些版本的软件需要该代码,但不需要此代码。
  • 代码已经过时了,但是写作需要花费很长时间才能完成。此外,它可能有一天会有用。

问题出现在你把代码放到床上,然后几年后回到它做一些维护。您会发现代码库中充斥着注释掉的代码。它将不再清楚为什么它存在,它现在只是杂乱无章。

如果您使用任何半正式版本控制工具,您可以大胆删除任何您不再需要的代码,安全地知道版本控制系统仍然存储它。版本之间的文件差异将显示已删除的内容。一旦你实现了版本控制,唯一需要注释的是临时的东西。如果您在文件中找到已注释掉的代码,那么您可以删除它。

2
额外
这些正是您应该使用SCM(以及其中的曲柄)的原因
额外 作者 Adam,

我不打算重申为什么你应该使用源代码控制甚至是单人项目,因为有很多其他资源会告诉你这样做。但是,当前方法的一个主要缺点是,如果您注释掉代码,则将其隐藏在IDE中(如果您不使用IDE,则应该考虑它)。

例如,如果要重命名方法或类,或者更改方法所使用的参数数量,IDE应该有一个重构选项来执行此操作,该选项将找到所有相应的引用并相应地更新它们 - 但它可能赢得了'在评论中搜索。

不要试图猜测你需要做出改变的地方,而是让它们成为它们,让你的IDE告诉你你的改变导致了什么破坏。然后你可以更加手术地注释掉代码,希望在你解决任何破坏之前的更短的时间内。

2
额外

这是糟糕,你应该停止

原因归结为试图一次性进行大量的重构。

如果您注释掉大部分代码,修改一下并签入,那么您已经签入了非功能代码。并且其他人将承担的一大堆注释掉的东西已经过时,可以被忽略

如果您不经常登记,那么您正在累积合并冲突而不是逐步记录进度。

你需要改变你的工作实践,这样如果你必须在中途停止一切仍然有效。

在每个步骤后,请采取婴儿步骤并检查:

  • 提取界面
  • 写一个测试
  • 重构函数

不要将大块代码标记为“你的”,将它们注释掉并将它们带走,直到它们完成或失败为止。

如果您需要跟踪需要完成的工作,请使用scrum或trello等任务板

1
额外