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

我曾在一家生产至关重要的软件的商店工作过，还处理过一些注释规则，这些规则旨在保持代码的可读性并可能挽救生命。以我的经验，尽管要求变成了脑筋急转弯的工作，需要从清单中剔除，但这并不能帮助我专注于编写可理解的代码。这也分散了我的同行审阅者的注意力，使我无法就如何使代码更易于理解进行更有意义的对话。

我还对没有注释的学生代码进行了评分，并查看了为什么应将它们标记为忽略它们。

我知道使用好名，使结构简单，函数简短，并关注模块将使代码易于理解，从而可以最小化注释。

我也理解注释应该解释为什么代码会执行此操作，而不是如何执行。

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

在清单中被视为一行时，此规则可能需要的代码示例：

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

如果有可能在标准文档中正确表达这一点，但可能不是这样，我想遵循以下思路：

考虑对代码的每一行，每个序列，语句，部分，结构，函数，方法，类，程序包，组件，...的注释。接下来考虑重命名和简化以消除对该注释的任何需要，因此您可以将其删除。在评论很少的情况下签入。重复直到截止日期。然后再重复一些

迈克尔·杜兰特（Michael Durrant）的回答是恕我直言，还不错，但这并不是从字面上回答这个问题（正如他本人所承认的那样），因此，我将尝试给出一个答案：

我也理解注释应该解释为什么代码会执行此操作，而不是如何执行。

鉴于所有这些，甚至有可能编写出能够抓住这一想法的良好编码标准？

显然，您可以为代码审查编写清单，其中包含诸如以下问题

• “如果有评论，它是否解释了代码为什么要这样做？”
• “代码的每一行-在其上下文中-是不言自明的以至于它不需要注释，或者如果不需要，它是否伴随着注释来弥补这一空白？或者（最好）是否可以更改代码，以便它不再需要评论了？”

如果愿意，可以将其称为“编码标准”（或者不可以，如果您认为术语编码标准应保留给脑死亡规则的列表使用，则可以轻松回答是否满足这些规则，以及如何格式化代码）应该看起来像，还是在哪里声明变量）。没有人会妨碍您将清单的重点放在语义问题上，而不是走简单的路线，只把正式的规则放进去。

归根结底，您应该确定您的团队需要这样的清单。要解决此类问题，您需要具有一定经验的程序员作为审阅者，并且需要在专家团队中找出它是否真的可以提高代码的可读性。但这是您必须与团队共同努力的事情。

严重的反模式导致代码质量较差且清晰度较低

顺便说一句，读者的标题最初是“评论每一行代码？” 您可以想象我们当中包括我在内的许多人的本能反应。后来我改名了更长的标题。

开始时，我想念您的问题，评论中有很多重复的内容，但是，好吧，如果您对多人的评论有足够的限制...但是然后又重复了：人们会犯错误，无法注意到不一致之处，等等。最终会有分歧。经过反思，我认为问题要大得多：

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

考虑：

living_room_set = tables + chairs.

现在考虑：

set = tbls+chrs # Make the set equal to the table plus the chairs

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

摘要

如果您被迫担任开发人员的当前职位（如果是以前的COBOL编程专家，我肯定见过很多！），但要花很多时间，精力和精力来反对评论反模式使用参数：

• 仅更改一项时，代码和注释便会彼此不同步

• 评论可能会描述一个人的想法，但可能是错误的，从而掩盖了错误

• 代码变得更难阅读

• 好的代码变得很难编写

• 倾向于使用更多神秘名称

• 过多的字符需要阅读代码和注释

• 不同的编辑使用不同的样式

• 与编码相比，要求更高的英语水平

• 花费时间和资源并从长期价值中减去 *

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

两个棘手的问题之一是命名问题-不要一边用注释跳过问题。

鉴于其他问题之一是过早的优化，并且一般而言，优化可能导致模糊的“为什么采用这种方式”代码，因此，尽管上述警告仍然适用，但在这方面，对于看似较差的代码的解释性注释可能是有益的。

* 明天的代码

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

这样的评论在客观上是没有用的，并且可能是由于没有经验的开发人员，或者是曾经使用过构建系统的开发人员以机械方式检查注释的存在（确实很糟糕，但是确实存在）。在这两种情况下，解决方案都是教育，可能需要通过代码审查。

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

这不可能。您本质上想做的几乎是机械化良好的判断力。

在编写关键软件（例如用于生命支持医疗系统的软件）时，大量清单和其他清单几乎是不可避免的。不仅聪明的人都会犯错，而且这些设备的许多软件都是由不太擅长工作的人编写的，因此“系统”必须能够防范草率的工作，使其安全牺牲适销性。

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

更新资料

我在报价中的回应强调：

我认为，指出注释的问题的答案不应在编码标准中解决，然后列出一系列防御性问题加以解决，这是唯一正确的答案。

这里的问题是，编码标准就是标准。非常主观的想法应该不会是在编码标准。它可以是“最佳实践”指南中的，但是在“代码审阅”期间不能针对开发人员使用该指南。我个人认为，编码标准应尽可能接近自动。当所有代码都可以自动执行时，在代码审查中浪费了很多时间来争论命名，间距，制表符，括号，注释等。甚至对答案tables，并chairs可以实现自动化。LINT'ers允许使用字典，每个概念的大写检查（变量，函数，方法，类等）。

在接受“拉取请求”之前，甚至可以由Robot LINT'er实施JavaDoc检查。许多开源项目都可以做到这一点。您提交“拉取请求”，该代码是使用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仍在使用此类旧硬件和软件的原因。当涉及到生与死时，您不只是“做些改动并签入”。

评论与挽救生命无关。评论是针对人类的，即使编写评论，人类也会犯错。不要相信人类。恩，不要相信这些评论。评论不是您的解决方案。

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

文档向您介绍一段代码的外向位-接口。

通常，工具可以使您以“独立”方式阅读它们，即您不会同时查看基础代码。

所有接口都应记录在案（例如，每种方法，不包括私有方法），并应描述输入，输出以及任何其他期望，限制等，尤其是不能通过约束，测试等表达的东西（究竟有多少细节以及它的去向取决于项目）。

好的文档可以使潜在的消费者决定是否，何时以及如何使用代码。

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

注释总是在基础代码中读取。

评论应说明令人惊讶的决定或复杂的算法，或未采取的选择（和推理）。他们在那里，以便将来的开发人员可以了解其前任的思维过程，并掌握手头的信息，否则他们可能会忽略这些信息或花费大量时间进行搜索，例如

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

您不能从没有注释的情况中推断出任何内容，并且注释当然可能与周围的代码一样错误，甚至更多。作者和读者都必须做出判断。

注释每一行显然是更多可疑的附加价值工作，这伴随着机会成本。如果你有一个规则说每一行加以注释，你会得到，但在重要的部分费用被评论很好。

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

注释和文档均未提供对其描述的代码质量的任何度量或保证；它们不能代替真正的质量检查。他们的目的是前瞻性的，即希望他们能帮助与之互动的人避免犯错。

总而言之，您的编码标准可以并且应该需要文档（自动检查有助于发现未记录的功能/方法，但是人员仍然需要检查文档是否有好处）。评论是一个判断电话，您的样式指南应该承认这一点。那些从不发表评论的人，以及那些没有思考而发表评论的人，都应该受到挑战。

您无法编入评论标准，因为您无法事先知道重要的评论。

但是您仍然要确保代码正确注释，因为这是至关重要的代码。解决方案是为代码审查制定标准-要求代码审查意见具有易懂性。

这不能保证它不会变成毫无意义的检查表，但是至少可以防止它使代码更难阅读。并有可能使其变得更好。

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

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

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

注释每一行代码？没有。

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

对可读代码的注释充其量是多余的，而在最坏的情况下，会使读者放弃寻找注释不存在的目的。

如果您对整个代码进行注释，这是不言自明的，那么您在不给出任何其他信息的情况下将阅读量增加了一倍。我不确定这种冗余是否会奏效。可以想象一个审阅者说42表示“ display_error”，而评论说“显示警告”。但是想象一下代码中的变化。您现在有两个地方要更正。很明显，这种风格具有复制粘贴底片。

我想说的是，除了文档之外，代码最好不需要任何注释。

有些样式完全相反，如果您对线条有疑问，可以选择两种：

1. 代码太复杂了，应该将其重构为一个函数，该函数的名称应具有代码部分的语义含义。它是if算法的复杂还是一部分。（或者聪明的LINQ单线）

2. 如果无法简化，您将不了解足够的语言习语。

（我个人不是严格的无注释规则的狂热者，但我认为这是一个很好的初始思路。）

鉴于所有这些，甚至有可能编写出能够抓住这一想法的良好编码标准？

至于过程。我们的标准对审稿人功不可没。假设它们不是恶意的，则效果很好。

当他问“什么是变量o？”时，您将其重命名。如果他询问此块是做什么的，请重构或评论。如果有人争论是否清楚，或者审稿人没有弄清，那么就定义而言不是。在极少数情况下，很少有朋友提出类似第二意见的东西。

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

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

问题：

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

评论不应试图教育读者使用该语言。应该假定读者比作家更懂该语言，但上下文却比作家少得多。

您的示例中的这段代码的读者应该知道这exit()将退出应用程序-因此使注释多余：

/* Exit the application */
exit();

冗余的意见是违反干的，并修改代码不一定传播到评论，留下不反映什么代码实际上做评论。

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

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

谨慎使用内联注释。

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

内联注释是不必要的，并且如果它们表明显而易见，则实际上会分散注意力。不要这样做：

x = x + 1                 # Increment x

但是有时候，这很有用：

x = x + 1                 # Compensate for border

举这样的例子，我个人更喜欢走得更远，并且也会尝试消除这一评论。例如，我可能会得出：

border_compensation = 1
compensated_x = x + border_compensation

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

回到实际问题：

鉴于所有这些，甚至有可能编写出能够抓住这一想法的良好编码标准？

我相信PEP 8指南和示例演示了捕获此思想的良好编码标准。是的，我相信这是可能的。

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

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

编辑----

只是为了澄清。我没有评论最好的评论vs tdd vs单元测试。或建议每行评论是好/坏

我只是建议一个原因，您可能会看到示例中讨论的评论风格。

从这个问题上，关于注释的编码标准实际上是否可以更好地写成某种规格文件的要求。

即，注释用于解释代码的目的，这也是规范

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

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

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

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

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

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

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

因此，不是注释行，而是更大的代码段。是否应注释每段代码？否。哈罗德·阿伯森（Harold Abelson）说：“ 必须编写程序供人们阅读，而只能由机器执行 ”。但是注释仅供人阅读-机器不执行它们。如果您的编码标准强迫在每行代码/代码段上写多余的注释，那么您不仅在负担需要编写它们的开发人员的负担，还在负担着必须阅读它们的开发人员的负担！

这是一个问题，因为当您阅读的大多数评论都是多余的时，您将不再关注它们（因为您知道它们只是多余的垃圾），然后您将错过重要的评论。因此，我说-只写重要的注释，这样当有人在代码中看到注释时，他们就会知道有必要阅读该注释才能理解代码。

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

  i++;    /* Increment i */

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

OTOH，如果您在函数的开头（或任何逻辑上的分组）处编写了一个良好的注释块，既描述了要完成的工作，又描述了如何做（如果不那么明显的话），那么您将很有用。如果您是我，您甚至可能包括用于相关方程式的LaTeX代码，或对论文的引用，例如：“这实现了WENO方案，用于解决Hamilton-Jacobi方程，如...所述。”

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

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

我将回答上述问题：

鉴于所有这些，甚至有可能编写出能够抓住这一想法的良好编码标准？

是。所见即所得。一个好的编码标准从字面上是“ 对于读者来说清楚以下代码的作用以及原因 ”。

换句话说，我的代码审查评论从字面上看是关于代码可读性的1-1，这是由于我的心理状态

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

通常，当人们听到“我作为高级开发人员，希望您不要傻瓜，他们一开始没有读懂此代码或为何有此代码或什么内容时，人们很容易上手”这需要更高的可读性”这样做，所以需要解释”。

这将论述从“您没有遵循毫无意义的标准”转变为“您的代码具有导致实际问题的特定可读性缺陷”。

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

当您在没有手机的智利安第斯山脉度假时，如果您没有使用此代码的经验，您的备份人员能否在凌晨2点紧急生产桥接电话中调试该代码时找出该代码的问题？

这听起来可能是主观的，但实际上实际上很容易衡量：召集一个随机的初级团队成员，预期该团队将在生产紧急情况下在夜间进行调试，并请他们解释未注释的特定代码如何工作以及为什么这样做那里。

这个答案涵盖了大多数问题，但是有一件重要的事情。

我想从以下方面捕捉一个想法：考虑每行代码，序列，语句，部分，结构，函数，方法，类，包，组件，...的注释。

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

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

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

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

话虽如此，这取决于开发人员使用哪些工具，并且并非此类软件使用的所有注释都一样有用。