我什么时候应该在我的代码中添加注释？

Question

• 当我写作的时候？
• 完成一部分后（Single class / function / if-elses）？
• 我完成整个工作后？

Answer 1

简短回答

简短的回答是任何时候相对于阅读它的东西是不明显的。如果它的代码仍在不断变化，那么你就是唯一的消费者，只需为你评论（小时和天）。准备办理登机手续以便其他人试用 - 为您和您的团队提供意见（数天和数周，可能是数月）。准备广泛发布 - 对即时和未来公众（月和年）的评论。您必须将注释视为工具，而不是文档。

答案很长：

• 当我写作的时候？ - Yes
• 我完成一部分后（Single class / function / if-elses）？ - Yes
• 我把整件事搞定了？ - Yes

当我写作的时候？ - 是

只要您找到代码未立即清除的地方，就可以删除评论。例如，在类名不清楚或可能解释得过于广泛时描述类。另一个例子是，如果我要编写一个非显而易见的代码块，我将首先添加一条注释，提醒我我想要/需要什么。或者，如果我只是添加了一些代码，我立即意识到那里有一个问题，请发表评论以提醒自己。这些评论是实现者评论，不是为了帮助未来的维护者，而是为了帮助自己完成编码过程。

随时删除FIXME - explanation和TODO explanations提醒。

代码仍在不断变化，所以我还没有记录每一个方法和参数。

我完成一部分后（Single class / function / if-elses）？ - Yes

当我合理地完成一个方法或类时，现在是时候审查它了。除了检查方法范围，排序方法和其他代码清理以提高可理解性之外，现在是时候开始根据团队标准对其进行标准化。根据将要发布的受众群体考虑需要哪些评论（未来您也是受众群体的一部分！）该类是否有标题块？是否存在不应该调用此方法的非显而易见的条件？此参数是否具有任何条件，例如不应该为空？

检查FIXME和TODO项目 - 仍然有效吗？在继续之前你应该解决的任何问题吗？

这些仍然是您和您的团队的笔记，但是未来维护者的标准化笔记的开头。

我完成整个工作后？ - Yes

现在是时候审查所有内容并根据您的标准最终确定评论。

所有FIXME和TODO项目已解决（已修复或已捕获为已知问题）？

这些说明现在适用于未来的维护人员。

现在是一个肮脏的小秘密

更多并不总是更好。与unit tests一样，您必须平衡使用工具来衡量成本与收益。事实上，编码器每小时只能输入这么多物理线路 - 应该注释多少百分比？较低的百分比意味着我有很多代码，但它令人困惑，难以理解和正确使用。较高的百分比意味着，在某人更改方法签名或重新定义界面的一小时内，所有时间都花在完全评论那些被破坏的方法的每个参数上。

根据代码的稳定性，生存时间以及发布的广泛程度，找到合适的百分比。还不稳定 - 最少的评论可以帮助您和您的团队。稳定并为项目做好准备 - 完全评论。公开发布？ - 完全评论（再次检查！）版权（如果适用）。获得经验后，请调整百分比。

Answer 2

你永远不应该“添加”评论 - 它们不是补充。注释是代码的一部分 - 您可以在需要时使用它们。询问何时应该添加它们就像询问何时应该添加函数或类一样。考虑到这一点，我记得在大学里做了一个项目建议，我曾为一名学生带来了大约1000行Pascal，没有任何功能。当我询问他为什么没有使用函数时，他的回答是“我会在以后添加它们，一旦我开始工作。”

Answer 3

这是主观的，但有时最好在实际代码之前添加它们，例如。当您实现具有明确定义的步骤的算法时。通过这种方式，很难错过任何步骤。

Answer 4

这是一种风格问题。就个人而言，我喜欢在编码期间写评论，而不是之后。因为我把它留给以后，我通常会变得懒惰而根本不写它们。也就是说，有时候查看完成的代码是很有用的，找出代码本身不明显的内容并记录下来。特别是，做出假设的部分。

Answer 5

在编写任何代码之前，您应该尝试编写注释。例如

public string getCurrentUserName() {
    //init user database repository


    //retrieve logged in user


    //return name if a user is logged in, otherwise return null

}

在编写代码之前编写注释，可以帮助您学习如何构建代码而无需实际编写代码并意识到您应该以另一种方式完成代码。这也是一种快速可视化复杂问题的清洁解决方案而不会陷入实施困境的好方法。这也很好，因为如果你被打断，当你回到工作岗位时，你可以直接回到它，而不是重新定义你做了什么以及接下来需要做什么。

不适合所有情况，但往往是一个不错的选择！

Answer 6

我建议您在编辑任何代码时编写注释，在编辑时。根据Robert C. Martin在Clean Code中的说法，评论的一个缺点是代码可以在没有更新注释的情况下进行更改，使得注释不仅无用，而且危险。要减少此问题，如果您必须使用注释（因为您无法在代码本身中表达自己），请确保每次更新代码时都更新它们。

Answer 7

稍后添加评论的一个缺点是，由于懒惰，其他任务等原因，很多时候根本就没有这样做。

如果您发现可以随时返回并添加相应的注释而没有任何问题，那么一定要这样做，但是在编码时或者在编写部分之前有意识地添加它们可能是确保您不要取消注释代码的方法。

Answer 8

发表评论任何程序员都在阅读你的代码，可能会产生一个WTF时刻。

如果您发现自己在评论每一行，或许您需要考虑使用更简单，更优雅的语句来尝试改进代码。

Answer 9

我倾向于在我写作时提出基本的评论，只是为了提醒自己在写作时我在想什么（也就是为什么我这样写的）。我这样做，特别是如果它的代码看起来可能是错误但实际上是正确的，或者代码具有我不关心的固有竞争条件，或者代码可能不是最佳但是快速获取某些东西的方法工作，所以即使十分钟后，当我回去看看时，我可以看到我已经考虑过这个问题而且不必浪费任何脑循环。

当代码更完整时，我会经常回去查看我写的评论，然后考虑一下我是否仍然认为做出的决定是合理的，以及是否可以做得更好。我还经常将基本评论扩展为更长的评论，当他们来维护代码时，这些评论对其他人更有用;我通常会将评论扩展保存到最后，因为很多时候基本评论会在重构过程中被删除，所以写一个长评论是浪费时间，直到你知道你要保留它为止。

简而言之，随着时间的推移编写基本注释，然后在代码变得更稳定时对其进行改进。

哦，而且，每当你查看一些现有的代码并且你被WTF震惊了？！那个时刻然后意识到代码实际上是不错的，发表评论以拯救自己和下一个人将来看待它的时间。

Answer 10

问题应该是，我何时在我的评论中添加代码？

我的做法是将模块/对象/功能的功能写为一系列注释。不是像“添加一个到柜台”这样的评论。更高级别的评论如 “按帐号排序列表”。代码中的详细注释几乎是多余的。所以除非我正在写一个非常棘手的算法，否则我会避免这些。 一旦我在评论中“设计”了功能，我就像人工编译器一样 在每行评论后添加代码。

尝试一下，让我们知道它是如何工作的！

Answer 11

就个人而言，我倾向于在必要时编写注释来总结代码 - 通常在编写代码之前，以及保存WTF。我把它们当作笔记 - 把事情做的事情，我用这种方式做的事情，或者用这种方式对待它们，然后把它们放在我认为需要的时间和地点。

Answer 12

在您忘记要实施的代码的规范和设计之前。 在你忘记之前，一些不幸的程序员将不得不在以后阅读它。 在你忘记那个不幸的编码员可能就是你之前。

Answer 13

当你在写作时，当你做一些非平凡的事情时。

Answer 14

我在编写任何不易理解的代码时添加注释。我发现，如果我不立即这样做，那就会被遗忘。我（或者更可能是其他人）然后花更多的时间来弄清楚我做了什么，而不是写评论。

更准确地说，在编写代码后立即进行注释是确保实际写入注释的最佳途径。

Answer 15

你在问题​​中提出了很多案例。我认为这取决于你当时在做什么。

如果您正在编写函数或类，则注释是一种声明函数应该发生什么的方法。输入变量，输出类型，特殊行为，异常等等。在“代码设计”阶段，应该在实际代码启动之前编写这种注释。大多数语言都有将这些注释处理成文档的包（javadoc，epydoc，POD等），以便用户可以读取这些内容。

如果您正在编写一些代码，我认为可以等到您努力发表评论，胜利地描述您的工作解决方案。这种评论只能由代码审查员阅读。

然后，正如其他人所说，你想要自己或他人避免WTF时刻。我曾经在一个开源项目中做过一次评论，我曾经有过一个评论。评论是“是的，我真的想要=而不是= =那条线。”

Answer 16

一个。当你决定一个难以重新理解的任意决定时。 B.在编写代码时，您认为应该记住的每件事情 C.在程序开头讲解逻辑和使用 建议 - 而不是批评很多使用长名称的函数和变量，真正解释函数的作用或变量的含义。

Answer 17

主要是在你编写代码的时候。您可以在功能/阻止/完成任何操作之后去那里，并以新的心态组织您的评论。我们在编码时编写的大部分内容以后都没有意义。

Answer 18

在我职业生涯的早期，我几乎在每行代码中都添加了注释，就像你在ASM程序中所做的那样。随着时间的推移，我遇到了很多这里提到的问题。这是一个坚持的熊，导致没有更新评论，然后它们变得陈旧，通常发霉。

我觉得评论的＃应该反映代码本身的复杂程度或非显而易见性。在更具挑战性的环境中，例如ASM，您可能需要更多评论来了解正在发生的事情。在像C＃这样的更现代的语言中，在大多数情况下你不需要大量的评论。

通常我使用的工具可以评估C＃中方法的复杂性。那些复杂程度较高的人首先得到重构。然后，当我对剩余的复杂性感到满意，并且我仍然有一些不明显的代码，或者甚至更重要的代码，似乎显而易见但做了不同的事情，然后我对它进行评论。

Answer 19

评论应该反映出你按照自己的方式做事的原因，而不是它的作用。大多数情况下，阅读代码的人都可以阅读它的内容。

你应该解释代码中无法减少的事情。