在高周转环境中，更多评论更好吗？

我今天在和一位同事聊天。我们为两个不同的项目编写代码。就我而言，我是唯一编写我的代码的人。在她的案例中，有多个人在同一代码库上工作，包括相当定期（每8-12个月之间）来来去去的合作学生。她说自己对自己的言论持开放态度，无处不在。她的理由是，它可以帮助她记住事情在哪里以及做什么，因为许多代码不是她编写的，并且可以由她以外的其他人更改。同时，我尝试将代码中的注释减至最少，仅将它们放在不明显的解决方法或错误的地方。但是，我对代码整体有了更好的了解，并且可以对其进行更直接的控制。

我的意见是，评论应尽量少，代码应能说明大多数情况，但她的推理也是有道理的。她的推理有什么缺陷吗？它可能会使代码混乱，但是如果有很多人在中短期内对其进行操作，则最终可能会很有帮助。

注释不会使代码混乱。

而且当他们这样做时，每半个体面的IDE都可以隐藏/折叠注释。理想情况下，故事应该通过代码，需求文档，提交历史记录和单元测试来讲述，而不是通过注释来讲述。但是，仅当评论集中在如何而不是为什么上时，过多的评论才会受到伤害，但这是另一种讨论。

我认为您和您的同事都是“正确的”，区别当然是您独自工作，而她在一个团队中，通常包括经验不足的开发人员。您在注释方面没有太多不同的哲学，但是在传达代码方面有非常不同的要求。“帮助我记住”的说法还可能源于这样一个事实，即她处理的代码比您多得多，更重要的是由不同人员生成的代码，每个人都有自己的个人喜好和怪癖。

归根结底，代码注释尽管有明显的缺陷，但却是传达代码的最简单，最快的方法。根据团队的组成和组织，它甚至可能是适用于最低公分母的唯一方法。我通常会发现自己在独自工作时会遵循您的评论理念，而在团队工作时会适应同事的想法，尤其是在团队技能不平衡的情况下。

在这种环境中，多产的评论掩盖了应该以另一种方式解决的问题。

优质易读的代码永远不需要其他注释来解释其功能。唯一要发表评论的时间是当您想解释为什么以某种特定方式完成某件事时。即使那样，这些注释也可以说是在源代码管理提交消息中。

因此，她要解决的问题是她必须与不知道如何以可读方式编写代码的学生一起工作。我认为，用注释使代码混乱是解决该问题的一个较弱的解决方案。

严格的代码审查将更加有效，无论是保持代码整洁还是改善将来的学生，无论是在同一公司还是在其他地方。

注释的问题在于，它们往往会很快与代码不同步。这意味着代码中经常会出现误导性或直截了当的错误注释，因此它们对可读性的损害大于帮助。

目的是使代码库易于理解和修改。您可以通过自由使用注释来做到这一点（尽管您可能会在数据注释中遇到问题），或者可以编写自文档代码（尽可能多），并且仅使用注释来解释非平凡的“为什么”问题。每种方法都可能有效，但请记住，要修改代码，您必须理解代码本身，而不仅仅是注释。因此，尽管注释可以帮助您理解代码，但最终还是需要理解代码本身。话虽如此，我更喜欢使用自文档代码方法。这似乎是创建干净代码库的更直接的方法。

“在高周转环境中，是否有更多注释更好？”

我认为它们可能会更糟：

• 不同的作者将使用不同的样式和详细程度，并且不会过多地更新他人的评论。

• “需要评论什么”的观点因人而异。

• 他们继续编写难以用注释阅读的代码来解释代码，而不是使用具有描述性名称的易于阅读的代码。

• 保持其格式和一致性本身就是一项工作。

• 新用户必须先学习“格式”标准，然后才能进行快速更改。

要点1：清晰度在高周转环境中很重要

要点2：详细不是清晰

在代码中添加注释可能会或可能不会提高清晰度；这取决于您添加的评论。一旦达到最佳清晰度，其他注释将使情况变得更糟，而不是更好。

尽管注释是清晰性的组成部分，但是代码质量是重要得多的组成部分。聪明与清晰相反。如果通过随意阅读不能立即看到代码的功能，则代码不是特别清晰，注释（无论注释的质量如何）都不能替代清晰的代码。

例如，在某些情况下，完全可以允许在无关字段的高位填充标志，并且在某些情况下，从性能的角度来看，这可能会带来很多负担，但是从清晰度的角度来看，这总是一个坏主意。 ，即使您发表评论。

如果发现自己必须在散文中解释代码的功能，请考虑以下任何一项：请注意，其中一些可能会影响性能，但是在某些情况下性能可能不如清晰度重要。

• 更好的变量名和函数名
• 更好的代码布局和间距
• 删除您认为不错的“技巧”
• 根据概念功能对代码进行分组（例如，将特定目的的代码提取到适当命名的函数中，即使您仅调用一次）
• 使用更简单的算法（条件允许）
• 使用知名的库来实现常用功能

一个过于简单的答案：“代码被重读的可能性越大，解释您所做的工作的负担就越大。” 这可能是通过使代码更易于阅读，通过评论它，通过创建正式文档，按照风格标准......请注意，这可能是你正在做以后重读，但它肯定也是别人的真高周转环境。

还有一个很棒的主题，涵盖注释是否为文档。

在某些情况下，注释比其他情况更有用。这是如此基础，以至于我担心如何在我认为是“反评论”的众多答案中进行解释。

如果您的代码可能多年未读，则注释比拥有频繁的代码重构，强大的代码所有权和大量的代码审查更为重要。如果您的应用程序很复杂，并且使用的语言对于熟练掌握该语言的观察者而言不是立即显而易见的，则注释比系统是美化的“ Hello World” 更为重要。如果代码库对标准的要求不严格，则注释要比使用六层质量检查更为重要。如果您与一个只有8个人一起学习语言的团队一起工作，则注释要比团队中有8个编程Pulitzers 更为重要。如果您的应用程序庞大，比起您能够从头开始构建它，注释更重要。

在大多数情况下，解决根本原因而不是增加注释的使用量会更好吗？绝对。但是有时您会遇到比城镇智能手机拥有更多指纹的代码库，而改进它的最佳方法是使您的更改尽可能可读并注释掉。

对于您的特定问题：注释不应过于分散代码。在子例程顶部的一段写得很好的段落，描述了一个函数为什么存在以及为什么它会使用这种方法，通常是最好的选择，以帮助下一个程序员理解。