为了清楚起见，编码标准：注释每一行代码？

#1 楼

迈克尔·杜兰特（Michael Durrant）的回答是恕我直言，还不错，但这并不是从字面上回答这个问题（正如他本人所承认的那样），因此我将尝试给出一个答案：解释为什么代码会执行它的工作，而不是如何执行。评论，其中包含诸如“

”之类的问题，“如果有评论，它是否解释了代码为什么要这样做？” -足够说明性，不需要注释，或者如果不需要注释，是否附带注释可以缩小差距？或者（最好）是否可以更改代码以使其不再需要注释？”

如果愿意，可以将其称为“编码标准”（或者不可以，如果您认为术语“编码标准”应该保留给脑死亡规则的列表使用，那么如果不满足则容易回答） w代码的格式应该看起来像，或在哪里声明变量）。没有人会妨碍您将检查表的重点放在语义问题上，而不是走简单的路线，只将正式的规则放入其中。
最后，您应该确保您的团队需要这样的检查表。要解决这些问题，您需要具有一定经验的程序员作为审阅者，并且需要在专家团队中确定它是否真的可以提高代码的可读性。但这是您必须与团队共同努力的事情。

#2 楼

主要反模式导致质量较差的代码，但清晰度较低。

顺便说一下，标题最初是“注释每一行代码？您可以想象我们当中包括我在内的许多人的本能反应。

起初，我改了称号。

起初，阅读您认为的问题，评论中有很多重复的内容，但是好吧，如果您对多人的评论有足够的限制...但是再说一遍：人们会犯错误，无法注意到不一致之处等，随着时间的流逝，最终将出现分歧。经过反思，我认为问题要大得多：

开发人员将倾向于编写更糟糕的代码。他们将使用更多隐秘的名称和结构，因为“其注释中有解释-请看！”。

考虑：

living_room_set = tables + chairs.

您不仅要拥有更多的神秘名称和更多的可读性，而且还得来回回头，看一下代码，什么是集合？左看代码，右看注释，什么是tbls，左看代码，右看注释，什么是chrs，右看注释。 Yuch！

摘要

如果您被迫担任开发人员的当前职位，请开发或增强评论标准（作为前COBOL编程的人，我肯定看到过大的！），但花费了您大量的时间，精力和激情，使用以下参数来反对注释反模式：变化
评论可能会描述一个人的想法，但可能是错误的，从而掩盖了错误名称
要在代码和注释中读取过多的字符
不同的编辑使用不同的样式
与仅仅编码相比，要求更高的英语水平
花费时间和资源并从长期价值中减去*

再加上争取更好的代码而没有这样的注释-实际上有一个标准（！）-所有变量名都必须为full_english_words-有一个！因此，请将“标准”能量用于编写良好的代码和测试的标准。

两个棘手的问题之一是事物的命名-不要在注释旁跳过问题。一般情况下，可能会导致模糊的“为什么这样”代码，尽管上述注意事项仍然适用，但在这一领域中，对于显然效果较差的代码的解释性注释可能会有所帮助。

#3 楼

我不认为编码标准文档是指定已经是常识的地方。编码标准的目的是保证在合理的人可能不同意且没有单一明显的正确答案（例如命名约定，缩进等。

示例中的这种注释在客观上是无用的，并且可能是由于没有经验的开发人员或曾经使用过构建系统的开发人员来机械检查是否存在评论（一个非常糟糕的主意，但是它存在）。在这两种情况下，解决方案都是教育，可能需要通过代码审查。

如果您开始将各种“最佳实践”添加到编码标准中，则最终将重复出现在多本书中。只需向有问题的开发人员购买“干净代码”，“代码完整”和“实用程序员”，并保持代码标准精简即可。

#4 楼

这不可能。实际上，您要做的几乎是机械化良好的判断力。不仅聪明的人都会犯错，而且这些设备的很多软件都是由不太擅长工作的人编写的，因此“系统”必须能够防范草率的工作，使其安全

您最好的选择是省去严格的编码标准以发表评论，并以团队为榜样。通过努力产生适当注释的高质量代码来显示他人的良好注释。与其尝试找到描述如何编写注释的终极方式（它们本身常常是判断调用），不如通过自己的代码审查每天向其他人展示您的意思。当其他成员阅读您的代码时，如果他们觉得有用，他们也会效仿。如果他们做不到，那么没有标准可以帮助他们写出更好的评论。

#5 楼

更新
我在引号中的回答重点在于：

我相信答案中指出不应在编码标准中提及评论，然后列出了一系列防御性的问题可以解决。唯一正确的答案。
这里的问题是编码标准就是标准。极端主观的想法不应包含在编码标准中。它可以是“最佳实践”指南中的，但是在“代码审阅”期间不能将该指南用于开发人员。我个人认为，编码标准应尽可能接近自动。当所有代码都可以自动执行时，在代码审查中浪费了很多时间来争论命名，间距，制表符，括号，注释等。甚至有关tables和chairs的答案也可以自动化。 LINT'er允许使用字典，每个概念的大写检查（变量，函数，方法，类等）。
即使JavaDoc检查也可以由Robot LINT'er实施，然后才能接受Pull Request。许多开源项目都可以做到这一点。您提交拉取请求，该代码是使用Travis-CI文件（包括静态分析）构建的，并且必须通过所有可以客观表达的编码标准。没有人会抱怨“做错了”或“没有提供评论”，或者用错误的方式命名变量等。这些讨论没有任何价值，最好留给第三方机器人使用，它可以首当其冲。我们要真正回答这个问题，我们就必须解决如何编写一个标准，以解决该问题。以下问题：此评论是否有价值？编码标准不可能规定评论的“值”。因此，人类必须通过该清单。在编码标准中仅提及注释会创建清单，原始海报要避免。
这就是为什么注释通常不由编译器处理并去除的原因。它们的价值无法确定。有关评论是否有价值？是还是不是？。回答这个问题很困难。只有人类有机会正确回答它，即使如此，阅读它的人也只能在阅读时回答它。该评论的价值受天气，他或她的家庭生活，他们刚刚参加的上次会议影响不大，一天中的时间以及所喝咖啡的量的影响。我相信情况会越来越清晰。
如何在任何标准中正确地表达它？除非可以始终如一地公平地应用标准，否则标准将无用。公平是公平，更多的是客观性而非情感。

我认为编码标准应尽可能保持客观性。变量被称为IS目标的方式。可以根据字典轻松地检查它们的正确拼写，语法结构和大小写。除此之外，还有“小便比赛”，由最有力量的人或“眉头殴打”赢得。我个人不做某事感到很苦。如果我在5年后回到此代码，我需要知道什么？什么会有所帮助，哪些会造成混淆，哪些会与代码过时？生成可搜索的公共API的文档代码和为未知的第三方提供价值的注释代码之间有区别，即使该第三方是您自己。
这是一个很好的石蕊测试。如果您是该项目的唯一成员。您知道您将是该项目中唯一的一个。您的编码标准将是什么？您希望您的代码是干净的，自我解释的，并且将来对您自己可以理解。您是否会对自己进行代码审查，以了解为什么没有对每一行都发表评论？您是否会查看在签入的100个文件中创建的每个注释？如果不是，那么为什么要强迫别人？
我相信在这些讨论中遗漏的是，Future You也是该项目的开发人员。在询问价值时，明天的您也是可以从评论中获取价值的人。因此，在我看来，团队规模并不重要。团队经验并不重要，它会经常变化。
没有任何评论代码可以阻止起搏器坠毁并杀死患者。一旦谈论影响代码的注释，您现在谈论的是代码而不是注释。如果只是想写一条谋杀某人的评论，那么过程中还会有其他气味。本身。它与评论无关。评论的问题在于它们对产品最终的工作方式没有影响。嵌入心脏起搏器后，世界上最好的评论无法阻止软件崩溃。或者使用便携式EKG测量电信号时。
我们有两种类型的注释：
机器可读注释
注释样式，例如Javadoc，JSDoc，Doxygen等，都是注释一组代码提供的公共接口的所有方法。该界面只能由其他单个开发人员（两人团队的专有代码），未知数量的开发人员（例如JMS）或整个部门使用。可以通过自动化过程读取此代码，然后该过程将以不同的方式读取那些注释（例如HTML，PDF等）。这是确保每个公共可调用方法，函数，类均包含必需注释的客观过程。标头，参数，说明等。埃尔。这是为了确保另一个团队可以轻松找到并使用该代码。
我正在做一些看起来很疯狂的事情，但实际上并非如此。用一定的方式写。也许正在运行代码的处理器中会出现数字错误，并且总是四舍五入，但是开发人员通常会处理四舍五入的代码。因此，我们发表评论以确保开发人员接触代码后，通常理解为什么当前上下文在做某事通常是不合理的，但实际上是故意写这种方式的。它通常没有注释，后来被新开发人员发现并“修复”。从而破坏了一切。即使这样，评论也只能用来解释为什么不真正阻止任何破坏。
不能依靠评论
评论最终是无用的并且不能被信任。注释通常不会更改程序的运行方式。如果确实如此，那么您的过程会引起更多的问题，而应该这样。评论是事后的想法，只能说什么。代码很重要，因为这就是计算机处理的所有内容。
听起来似乎很愚蠢，但请耐心等待。这两条线中的哪一条真正重要？
// We don't divide by 0 in order to stop crashes.
return 1 / n;
在此示例中，重要的是我们不知道n是什么，没有检查n是否为0，即使存在，也没有阻止开发人员将n = 0放在检查之后0。因此，该评论是无用的，没有任何自动化方法可以解决。没有标准可以捕捉到这一点。评论虽然漂亮（对某些人而言）与产品的结果无关。
测试驱动开发
产品有什么结果？必须严格检查在其中编写代码可以真正保存或杀死某人的行业。这是通过代码审查，代码审查，测试，测试，代码审查，单元测试，集成测试，试用，分阶段，几个月的测试，代码审查和单人试用，分阶段，代码审查，测试来完成的投入生产。注释与此无关。
我宁愿没有注释的代码，没有规范的代码，具有验证规范的单元测试，研究在生产设备上运行代码的结果的代码，然后记录过的代码，从未进行过测试，也没有任何可与之进行比较的代码。
当您试图弄清楚为什么有人以某种方式做某件事时，记录很好，但是，多年来我发现文档通常用于解释为什么做了“聪明”的事情，而实际上并不需要那样写。
结论
如果您在一家需要对每一行都进行评论的公司工作，我保证项目中至少有两名软件工程师已经用Perl，Lisp或Python编写了自动文档程序，该程序确定了该行的工作方式，然后在该行上方添加一条注释。因为这是可行的，这意味着注释是无用的。寻找已经编写这些脚本的工程师来自动记录代码，并以此为依据来证明“每一行的评论”为何浪费时间，没有价值并可能造成伤害。有编程任务的好朋友。他的老师已规定必须记录每一行。因此，我可以看到这种思考过程的来源。只是问问自己，您要做什么，这是对的吗？然后问问自己；有什么办法可以通过这个过程来“游戏”系统吗？如果有，那么它真的增加了任何价值吗？不能自动编写单元测试来测试代码是否符合特定规范，如果可能的话，那也不是一件坏事。人类，确保它不会杀死他们的唯一方法是经过多年的测试，同行评审，试验，然后再也不会更改代码。这就是为什么NA​​SA仍在使用此类旧硬件和软件的原因。当涉及到生死攸关时，您不仅会“做出一点改变并检查一下。”
评论与挽救生命无关。评论是针对人类的，即使编写评论，人类也会犯错。不要相信人类。恩，不要相信这些评论。评论不是您的解决方案。

#6 楼

在谈论评论时，有两点不同。它们不相同，并且区别很重要。

文档向您介绍一段代码的外向位-其接口。允许您以“独立”方式阅读它们，即您不会同时查看底层代码。

所有接口都应记录在案（例如，每个方法，不包括私有方法） ，并应描述输入，输出以及任何其他期望，限制等，尤其是不能通过约束，测试等表达的内容（确切的数量和去向取决于项目）。 br />
好的文档可以使潜在的消费者决定是否，何时以及如何使用代码。

源代码中的注释具有不同的用途。他们在那里供人们查看源代码。它们主要描述实现。

注释总是在底层代码中读取。 。他们在那里，以便将来的开发人员可以了解其前任的思维过程，并掌握手头的信息，否则他们可能会忽略这些信息或花费大量时间寻求帮助，例如
无法从没有注释的内容中推断出任何内容，并且注释当然可能与周围的代码一样错误，甚至更多。作者和读者都必须做出判断。如果您有一条规则说必须注释每一行，那么您会得到的，但要牺牲重要部分的注释。

但这比这还糟：如果注释了每一行，那么注释的目的就无法实现。注释变得杂乱无章，使代码难以阅读：模糊而不是澄清。此外，不加选择的注释使真正重要的注释更难以发现。

注释和文档都不能提供任何形式的措施或保证来描述它们的代码质量。它们不能代替真正的质量检查。它们的目的是前瞻性的，即希望它们能帮助与之交互的人避免出错。 /方法，但是人类仍然需要检查文档是否有用）。评论是一个判断电话，您的样式指南应该承认这一点。那些从不发表评论的人和那些不加思考地发表评论的人都应该受到挑战。

#7 楼

您无法编入注释标准，因为您无法预先知道重要的注释。码。解决方案是要有一个代码审查的标准-要求代码审查对可理解性进行注释。避免使代码难以阅读。并有可能使其变得更好。

这需要一种文化，即代码审查本身并不是毫无意义的手势，将代码以难以阅读的方式发送回是一件好事，侮辱或烦恼。同样重要的是，一个说不清楚的地方并不被视为读者的失败。

在某种程度上，无法阅读的代码是不可避免的。因为作者沉浸在上下文中，并且只有当您知道x，y或z时，才会看到明显的事物。

因此，您将无法制定能够提供良好反馈的规则，但是您可以现场检查评论。甚至非程序员经理也可以这样做-因为真正的问题不是写的代码可读性强，而是代码的可读性，这只能由阅读它的人来决定。

#8 楼

注释每一行代码？否。

您所谈论的其他规则的目的恰恰是避免这种情况。

如果您注释不言自明的整个代码，则在不给出任何其他信息的情况下，您的阅读量将增加一倍。我不确定这种冗余是否会奏效。可以想象一个审阅者说42说“ display_error”，而评论说“显示警告”。但是想象一下代码中的变化。您现在有两个地方要更正。很显然，这种样式具有复制粘贴的底片。相反，如果您对行有疑问，则为：无论是复杂的if还是算法的一部分。 （或者聪明的LINQ单行代码）
如果不能简化它，您将不了解足够的语言成语。 ，但我认为这是一个不错的初始思路。）

鉴于所有这些，甚至有可能编写出能够捕获此想法的良好编码标准？过程。我们的标准对审稿人功不可没。假设它们不是恶意的，这很好用。如果他询问此块是做什么的，请重构或评论。如果有人争论是否清楚，或者审稿人没有弄清，从定义上讲不是。在极少数情况下，很少有朋友会提出类似第二种意见。

平均而言，您应该获得团队中普通程序员可以理解的代码。 IMO保留了多余的信息，并确保至少一个团队的其他成员可以理解该代码，而我们发现这是一个很好的最佳选择。

也没有绝对值。虽然我们是一小群。在5人小组中容易找到共识。

#9 楼

问题：


鉴于所有这些，甚至有可能编写出能够抓住这个想法的良好编码标准吗？在同行评审中将是相关的，但不会变成无意识的清单活动，不会产生比以下内容更有用的注释：“您忘记对第42行进行评论”。


评论不应试图对读者进行语言培训。应该假定读者比编写者更了解该语言，但其上下文却比编写者少。

从您的示例开始，该代码的读者应知道exit()将退出应用程序-从而使注释变得多余：

/* Exit the application */
exit();

多余的注释违反了DRY，对代码的更改不一定会传播到注释中，而导致注释无法代码实际上在做什么。

但是，解释您为什么要做某事的注释可能很有价值-尤其是如果您无法轻松地传达代码本身的含义。

Python的PEP 8（CPython标准库中的Python样式指南）为嵌入式注释提供了以下准则：


谨慎使用嵌入式注释。

内联注释是与语句在同一行上的注释。内联
注释应与
语句至少分隔两个空格。它们应以＃和单个空格开头。

内联注释是不必要的，并且如果它们声明明显的内容，则实际上会分散注意力。请勿执行以下操作：

x = x + 1                 # Increment x

但是有时候，这很有用：

x = x + 1                 # Compensate for border

给出一个这样的例子，我个人更愿意进一步走下去，并且也会尝试消除这一评论。例如，我可能会得出：

border_compensation = 1
compensated_x = x + border_compensation

使您的代码自我记录并不是一个新主意。

回到实际问题：


鉴于所有这些，甚至有可能编写出能够捕获该思想的良好编码标准？所以是的，我相信这是可能的。

#10 楼

我想当您看到这种评论时，有时会自己写这种方式，这是因为作者将规范写在评论中，然后遍历并实施每个评论。

面临编写一种编码标准的挑战，该标准产生的代码在其所需功能而非实际功能方面可以理解（这样就可以发现错误），那么我们是否真的在谈论如何定义，记录和链接规范至最终产品？

编辑----

仅作澄清。我没有评论最好的评论vs tdd vs单元测试。还是建议每行添加一个注释是好事还是坏事？

我只是在说一个原因，您可能会看到示例中讨论的注释样式。

质疑有关注释的编码标准是否可以更好地编写为某种规范文档要求。

ie注释用于说明代码的用途，这也是规范的含义

#11 楼

鉴于所有这些，甚至有可能编写出能够抓住这一想法的良好编码标准？与同行评审有关但不会变成无意识的清单活动，不会产生比以下内容更有用的注释：“您忘记在第42行发表评论”。


显然，它超出了文档范围-涉及代码的结构，选择的算法等。它甚至可以涉及需求分析和设计。

我的＃1规则是“不要记录明显的东西”。 ＃2规则是“写明显的代码”。

对于安全性至关重要的代码（感谢我，我从来没有做过），这是必要的，但远远不够。甚至可能必须强制要求必须避免使用哪些语言功能（我见过不止一个标准命令“您不得出于任何原因使用scanf( "%s", input );”）。

#12 楼

自记录代码的最佳实践并不是主流共识-尽管易于理解的代码比隐秘代码更好，这是众所周知的，但并不是所有人都同意是否必须始终重构复杂的代码，或者是否可以发表评论

但是，这场辩论是关于难以理解的代码段-您正在谈论注释每一行代码。难于理解的代码行应该非常少见-如果您的大多数代码行都像这样复杂，那么您将过度使用智能资产一线服务，您应该停下来！当然，有时有时候很难理解某行的角色，但这是它在更大的代码段中的作用-该行本身的作用几乎总是很简单。

因此，您应该而不是注释行-您应该注释代码段。特定的注释可能位于它们所引用的行附近，但是这些注释仍在引用较大的代码。他们没有描述该行做什么/为什么这样做-他们描述了该行代码做什么和/或该代码为什么需要它。

因此，不是应该注释的行，而是更大的行代码段。是否应注释每段代码？否。哈罗德·阿伯森（Harold Abelson）说：“程序必须供人们阅读，并且只能由机器执行”。但是注释仅供人们阅读-机器不会执行注释。如果您的编码标准强制在每行代码/代码段上写多余的注释，那么您不仅在负担需要编写这些注释的开发人员的负担，而且还在负担必须阅读它们的开发人员的负担！ >这是一个问题，因为当您阅读的大多数评论都是多余的时，您将停止关注它们（因为您知道它们只是多余的垃圾），然后您将错过重要的评论。所以我说-只写重要的注释，这样当有人在代码中看到注释时，他们就会知道为了理解代码而值得阅读。

#13 楼

恕我直言，它应该两者兼而有之。评论每一行都是很愚蠢的，因为您最后会看到

  i++;    /* Increment i */

这样的行，而对于为什么要增加i绝对没有任何线索。稍微扩展一下，您将拥有典型的Doxygen注释风格，该注释会产生大量的混乱，而没有提供有关代码用途或工作方式的任何想法。 （至少据我所知：我承认可以使用这样的系统编写有用的文档，但我不屏息。）

OTOH，如果在函数的开头（或任何逻辑分组）写一个好的注释块，描述要完成的事情以及如何（如果不那么明显）有什么用处。如果您是我，您甚至可以包含LaTeX代码以用于相关方程式，或参考论文，例如“这实现了用于解决Hamilton-Jacobi方程的WENO方案，如...所述。”

#14 楼

是时候恢复流程图了！ （不是真的，但是要等一会儿）

前几天，我找到了旧的流程图模板。我只将它用于家庭作业和笑话（您必须喜欢一个很好的愚蠢流程图）。但是即使到了这个时候，大多数仍在使用流程图的商业程序员仍从代码中自动生成它们（这完全破坏了流程图的初衷，这是编写更好代码的助手，并且在机器代码中非常有用。但是，使用高级语言时，流程图从拐杖变成了霍布勒，为什么？流程图的抽象与代码相同，因此所显示的注释很麻烦，因为它们与代码处于同一抽象级别。好的注释处于与代码不同的抽象级别。做到这一点的最简单方法是使用注释说明代码处理什么的原因；其他方法是将复杂的步骤分解为更简单的替代方法或获得经理级别的抽象。 />

#15 楼

我将回答上述问题：


鉴于所有这些，甚至有可能编写出能抓住这一想法的良好编码标准？是。所见即所得。一个好的编码标准从字面上是“对读者清楚以下代码的作用和原因”。

，换句话说，我的代码评论字面意义上的关于代码可读性的1-1是由我的心态


我作为读者（更好的是，作为最低标准，是经验不足但合理的读者的心智模型），不会理解以下代码的目的或工作方法


通常，当人们听到“我，作为高级开发人员，希望您不尊重自己”时，他们很容易加入“这需要更多的可读性”愚蠢，一开始没有读懂这个代码，或者为什么它在那里或做什么，所以需要对其进行解释。 “您的代码具有特定的可读性缺陷，从而导致实际问题”。

需要明确的第二个标准是“凌晨2点紧急测试”。


可以备份吗o不熟悉此代码，请在不带手机的智利安第斯山脉度假时，在凌晨2点紧急生产桥接呼叫中调试该代码时，找出代码的问题？ />这听起来可能是主观的，但实际上实际上很容易衡量：召集一个随机的初级团队成员，该成员可能会在生产紧急情况下在夜间进行调试，请他们解释未注释的特定代码如何工作，为什么它在那里。

#16 楼

这个答案涵盖了大多数问题，但是有一件重要的事情。 ，语句，部分，结构，函数，方法，类，包，组件，...代码。


有一些工具可以从代码生成文档，例如例如氧气。如果使用这样的工具，则注释文件，函数，类等是有意义的。即使函数名是自解释的，我仍在这样做是为了保持一致性，因为阅读文档的人们将不胜感激。 >

#17 楼

许多现有的答案都非常详细，但我认为重要的是要回答：


... [评论]与同行评审有关，但不会转变为无意识的清单活动...


对我来说，只有标准的注释可以通过询问缺少的注释来回答。换句话说：IDE或文档软件使用的注释。

这就是说，这取决于开发人员使用的是什么工具，并且并非此类软件使用的所有注释都一样有用。