如何说服人们评论他们的代码[关闭]答案

【问题标题】：How to convince people to comment their code [closed]如何说服人们评论他们的代码[关闭]
【发布时间】：2010-09-14 15:32:33
【问题描述】：

什么是说服他人评论他们的代码的好论据？

我注意到许多程序员更喜欢在没有 cmets 的情况下编写代码的感知速度，而不是为自己和他人留下一些文档。当我试图说服他们时，我会听到半生不熟的东西，比如“方法/类名应该说明它的作用”等。你会对他们说什么来改变他们的想法？

如果您反对评论，请离开 cmets。对于试图说服人们评论代码的人来说，这应该是一种资源，而不是其他方式。 :-)

其他相关问题有：Commenting code、Do you comment your code 和How would you like your comments。

【问题讨论】：

// TODO: 评论这段代码...有一天
“方法/类名应该说明它的作用”......为什么这个半生不熟？
我一直发现，大多数 cmets 行，当它们作为政策问题出现时，都是毫无用处的。他们最终陈述了不言而喻的内容，并将注意力从对读者来说重要的事情上转移开。相反，应该出于节省代码阅读器时间和精力的真正愿望而提出评论。通常这是通过提供上下文来完成的，其他时候，它可能是提供参考。它可能会链接错误描述或用例。
@YiLiu 我完全同意。这就是为什么我试图收集如何说服他们的想法——也就是说，如何让他们发展一种内在的动机，而不是如何给他们发号施令。 :-) 但是，唉，这样的事情不适用于当前的 Stackoverflow 版主，因为他们总是关闭可能会被固执己见的人破坏的问题，这有效地阻止了覆盖没有坚如磐石的事实的整个领域。 :-( 叹息！

标签： documentation comments

【解决方案1】：

只评论“为什么”而不是“什么”。到目前为止，我同意，应该从类或方法或变量名称中清楚它的作用和用途。重构它没有的地方，而不是评论它。

如果您采用这种方法，您将获得 cmets，并且您将获得有用的 cmets。程序员喜欢解释他们为什么要做某事。

【讨论】：

是的是的！ “方法/类名应该说明它的作用”是真的，但 cmets 的重点是“为什么”，即上下文，代码没有说明。
虽然我非常同意，但这根本不能回答问题，所以我是-1
+1。例如：将异常复杂的代码作为另一家公司产品中的错误的解决方法或作为主要的性能提升。

【解决方案2】：

向他们展示他们自己 6 个月前的代码。如果他们无法在 2 到 4 分钟内准确理解并概述它的作用，那么您的观点可能已经提出。

【讨论】：

好点 - 完全同意。为了跟进，您应该能够将其提供给团队中任何体面的程序员，并且该人也应该能够在 2 到 4 分钟内告诉他们他们的代码做了什么。
当然不是 cmets 应该使代码更易于理解，而是代码本身？如果有人没有写出非常干净易懂的代码，那么他们应该重构它，而不是用 cmets 给他们凌乱的代码添乱

【解决方案3】：

我的看法：

我不会。方法/类名应该说明它的作用。如果没有，要么是方法或类试图做太多事情，要么是命名不当。

我喜欢评论为什么，而不是什么。如果不清楚为什么代码使用一种方法而不是另一种方法，请评论它。如果您必须添加一个 hack 未使用的变量来解决编译器错误，请评论原因。但是像“//连接到数据库”这样的 cmets 是错误代码或错误策略的标志。名为 ConnectToDatabase() 的方法要好得多。如果它有“//Determine DB server IP”，也许应该把它拉到一个名为“DetermineDbServerIPAddress()”的方法中。

设计可以记录在案，但 cmets 通常不适合那种级别的文档。有了设计知识，以及一些关于为什么、什么和如何应该显而易见的问题。如果不是，与其说服他们评论他们的代码，不如让他们改进它。

【讨论】：

终于有人说对了。完全同意。
阿门...

【解决方案4】：

也许这只是需要从经验中学习的东西；具体来说，六个月后回到你自己的代码，并试图弄清楚你在写代码时到底在想什么（或者你在做什么）的经历。这无疑让我确信 cmets 并不是一个坏主意。

【讨论】：

我赞成这一点，因为我们都使用了基本相同的示例。有点吓人。顺便说一句，我已经完全通读了代码并想，“这个白痴吸烟的是什么？”在意识到这是我自己的代码之前。
我不太确定...我相信重建自己过去的心理状态仍然比其他人过去的心理状态更容易。
Thomas...你比我精神更敏锐。今天早上我穿衣服时，我经常搞不清楚自己在想什么！ :-D
我已经做过很多次了。维护自己的代码绝对是写好代码的最佳动力。
这就是我注释代码的原因。所以我知道我为什么要这么做

【解决方案5】：

给他们一些（至少约 500 行）可怕的、未注释的意大利面条代码来重构。确保变量没有逻辑命名。空格可选。

看看他们有多喜欢它！

过分苛刻，但一口气拿下两分。

写好你的代码。
评论它以便您和其他人知道它的含义。

我应该强调，这段代码不应该来自他们。注释对于理解自己的代码非常有用，几个月后，它们对于理解其他人代码的复杂部分也非常重要。他们需要了解其他人可能必须了解他们在做什么。

最后的编辑：评论质量也很重要。一些开发人员在他们的工作中拥有几乎 2:1 的代码与评论比率，但这并不能使他们成为优秀的 cmets。您的代码中的 cmets 可能很少，但仍然很有意义。

解释你在做什么。您的代码质量应该为您完成大部分工作。
更重要的是，解释你为什么要做某事！我见过很多代码，它们准确地说明了某事正在做什么，但我并不真正了解为什么开发人员（不幸的是，大多数时候我）一开始就认为这是一个好主意。

【讨论】：

我支持你。我添加了相同的答案，并在看到您的答案后删除了我的答案。 :)
你错了，你建议的示例任务可能会说服他们编写更简洁的代码，但这与注释代码无关。
这么好注释的意大利面条代码就可以了，是吗？
Stefan：我的回答针对两个问题。一小段讨厌的代码可能会教他们编写更好的代码，但是一大堆相互交织的课程却没有解释他们做什么/为什么要做他们所做的事情，这将教会他们为什么上帝在 cmets...
它是：“别碰那个，它很热！”与“他只会烧自己一次”相比。争论。有些人从前者那里学得更好，而另一些人则从后者那里学得更好。 Oli 的论点适用于后者，但只会惹恼前者。

【解决方案6】：

提醒他们阅读代码只能告诉他们代码做了什么，而不是应该做什么。

【讨论】：

确实：接口规范说明了它应该做什么。 cmets 告诉你为什么程序员认为它所做的就是它应该做的。
谁说意图没有随着时间的推移而改变；而 cmets 并没有完全忠实地更新......
如果他们不写cmets，他们也不更新功能设计规范的可能性有多大。

【解决方案7】：

如果您或其他开发人员尚未阅读 Code Complete（或 Code Complete 2），请停止您正在做的事情并阅读它。

突出的一点是“一个函数应该只做一件事并且做得很好”。当这样一个函数以它做得好的一件事命名时，还有什么需要评论的？

评论习惯于与他们应该描述的代码不同步。结果可能比没有原始评论更糟糕。不仅如此，开发人员知道 cmets 会老化并且不可信。因此，他们将阅读代码并自己辨别它实际上在做什么！这有点抵消了将 cmets 放在首位的意义。

虽然说函数名称也是如此，但它可能本来就很好命名，但名称中没有提到的加班新操作已添加到其中。

所有 cmets 似乎都将开发人员希望靠得更近的代码行分开，以便他们可以在每个屏幕上看到更多内容。我知道我自己对一段代码的反应，其中包含很多我必须理解的 cmets。删除所有 cmets。现在我可以看到代码在做什么了。

说到底，如果你要花时间把事情做好，你最好把时间花在重构代码上，以确保其尽可能合理地自我描述，而不仅仅是编写厘米。这样的练习以其他方式获得了回报，例如识别常见的代码块。

值得牢记的是，许多优秀的开发人员更喜欢编写清晰的 C#、Java，而不是那些具有所有假设和歧义的不太精确的人类语言。诚然，大多数有常识的人都会知道多少细节才是足够的细节，但优秀的开发人员并不是“大多数人”。这就是为什么我们最终会得到像 \\adds a to b and store it in c 这样的 cmets（好吧，这太极端了，但你明白了）。

要求他们做他们讨厌做但坦率地说不太擅长的事情（即使你确信这是正确的做法）只是一场已经失败的战斗。

【讨论】：

我完全不同意。我编写的代码可以有效地进行复杂的计算，并且出于充分的理由使用单独的函数来计算求和的不同部分。它需要一些简单的、精心挑选的 cmets 来将方程与代码联系起来。
虽然一般的编码练习并不包含复杂的计算。其中绝大多数是非常无聊的，当代码结构良好且命名良好时，它的自我记录。喜欢评论东西吗？
+1。说得好！只有在没有重新表述代码中已经说明的内容时才编写 cmets。
麦康奈尔在这一章中通过苏格拉底式的对话实际上支持了 cmets！自我记录有点像神话，即使不是不可能，也非常罕见。

【解决方案8】：

我不是在对你刻薄，但你应该将问题改写为 你如何说服其他开发人员作为一个团队工作？

说真的，有些人认为你可以读懂他们的想法。

如果您是敏捷团队的一员，代码是集体所有的，因此当您看到未注释、笨拙或难以阅读的代码时，请继续更改（重构）它，以便您理解它。如果人们抱怨，请告诉他们原因并坦诚相告。你发现它难以理解，并且没有人拥有代码。

【讨论】：

【解决方案9】：

我们的策略是进行系统的代码审查，并拒绝没有正确记录的代码（通过 cmets、正确的函数命名和组织等...）。如果审阅者不清楚，你就回到工作台，期间。

【讨论】：

【解决方案10】：

我会说“昨天我不得不阅读你的一些代码。我能够理解它，但少于或等于 5 行精心挑选的解释它如何实现其目标的评论会让我阅读它在大约十分之一的时间里，然后我本可以担心理解一个问题。我不傻，你也不聪明，因为你可以写一些难以理解的东西。相反，如果你能'不产生可读的文档+代码集合，那么你就不是一个开发人员。”

我很久以前就被灌输了这样的想法：如果你写了一些东西，而有能力的人却无法理解它，那是你的错，而不是他或她的错。这适用于自然语言的写作，也适用于编程语言的写作。

【讨论】：

【解决方案11】：

关于评论也有类似的讨论。这是人们在评论代码时遵循的规则：What are your "hard rules" about commenting your code?。一些答案也有很好的理由说明你想要评论你的代码。

【讨论】：

【解决方案12】：

说服一个人的最好方法是让他们自己意识到这一点。让他们调试注释良好的代码。它将向他们展示好的评论是什么样的 - cmets 没有用，除非它们真正传达相关信息（这通常是“为什么”，因为代码描述了“什么”）。他们会注意到它是多么容易。然后让他们回到他们的一些旧代码。他们会注意到这有多难。您不仅向他们展示了不该做什么，还告诉他们该做什么（这更重要）。你不必再做任何事情了。更重要的是，您不必尝试口头说服他们。他们只需要了解以自己的方式注释代码的必要性。这当然是假设需要注释的代码不是自我解释的。

【讨论】：

这种精确的技术在一个铁杆、反评论的同事身上奏效了。
有证据证明它有效总是好的。谢谢！ :)
注释，就像代码一样，需要维护。唯一比未注释代码更糟糕的是带有错误和误导性 cmets 的代码。我认为从尝试使您正在编写的内容可读的角度来编写代码要好得多。当你觉得有必要添加评论时，它应该感觉像是失败了——承认你无法简化以让其他人理解的复杂性。好的 cmets 是简短的、罕见的、简洁的和自我记录的。
“说服一个人的最好方法是让他们自己意识到这一点”.. 是的，20 年后我意识到到处都是 cmets 并不是一个好主意 :-)跨度>

【解决方案13】：

在您对 cmets 的渴望中表现出智慧，他们将更有可能倾听。

少即是多。

强调质量而不是数量。

在我的团队中，有人推动评论某些 API 中的所有内容。一些开发人员开始使用一种工具，该工具可以通过查看方法名称和签名来自动生成 cmets。

例如：

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

你能想出更大的屏幕空间浪费吗？你能想出比阅读没有提供新信息的 cmets 更浪费脑循环的吗？

如果从方法签名上看出来了，就不要说了！如果我能在几秒钟内弄清楚，请不要将其放在评论中。正如其他人所说，告诉我为什么你选择这样做，而不是你做了什么。编写您的代码，使其功能一目了然。

【讨论】：

【解决方案14】：

以身作则。当开发人员看到正确的事情时，他们很容易动摇，因此看到实际的实践可能会鼓励他们这样做。此外，您可以鼓励您的团队采用解决代码可维护性和 cmets 的代码指标。例如，代码分析会为没有摘要文档的方法产生错误。

【讨论】：

【解决方案15】：

我当前工作地点的当前编码标准是注释每个函数。像这样的空白规则是有害的，永远不应该存在。在某些情况下（其中一些很常见），添加 cmets 会降低可读性。

class User {
    getUserName() { /* code here */ }
}

在上述代码中添加函数头有什么意义？你还要说什么 besdies“获取用户名”。并非所有代码都需要注释。我的经验法则是：如果您没有添加函数签名没有的任何有用信息，请跳过 cmets。

【讨论】：

【解决方案16】：

评论应该是彻底的，在意图的层面上写的（为什么不是如何），并且很少见。

在编写代码时，我理所当然地倾向于合理地大量评论。然后，我回过头来尝试删除尽可能多的 cmets，而不会降低代码的可理解性。 > 80% 的时间这就像提取一个命名良好的方法一样容易，这通常会导致注释仅复制代码本身中的信息。除此之外，如果有一段代码“需要”注释，我会寻找简化或使其更清晰的方法。

代码应该是自我记录的，使用right techniques，您可以轻松完成 95% 的工作。一般来说，如果我签入的代码上还有任何 cmets，我认为它是失败的。

【讨论】：

【解决方案17】：

取决于你有多少权力......

我发现一个非常有效的方法是让它成为基于同行的代码审查的固定部分 - cmets 的积分。如果有评论说代码被错误地注释了，我会让开发人员对它进行满意的评论，这基本上意味着他们必须描述足够多的代码，以便我通过打印和阅读来理解它。我也会这样做。

值得注意的是，这在开发人员中很受欢迎，尽管这听起来像是狄更斯式的。发生了两件事。首先，人们开始评论他们的代码。其次，差评代码成为开发人员不太了解他们所写内容的标志（否则他们会描述它）。

唯一真正的缺点是 cmets 必须在修改代码以进行错误修复等时跟上代码。这在真正的开发商店中几乎不可能强制执行，但是一旦根深蒂固了足够的良好实践，它就会排序的自然发生。

顺便说一句，我更喜欢代码本身中的 cmets，而不是 Dostoevsky 小说作为文档字符串。前者对后来的程序员很有帮助。后者只是一长段过时的文本，填满了文档并误导了所有人。

【讨论】：

【解决方案18】：

让他们使用不熟悉的 API，但在未连接 Internet 的机器上进行编程（如果您现在可以找到他们的话），这样他们就无法访问 API 文档。如果他们试图使用非文档人员的代码，这实际上是他们强迫其他开发人员做的事情！

【讨论】：

【解决方案19】：

您还必须在这里区分两个不同的 cmets：

API cmets（javadoc 或其他类似文档）：您可以向 use their own code in a limit scenario（边界条件如空对象或空字符串或...），看看他们是否真的设法记住在这些情况下他们自己的功能是什么
（这就是为什么我支持完整的 javadoc，包括限制值）
内部 cmets（在源代码中）：您可以要求他们解释他们编写的任何函数，只需选择一个带有 really high cyclomatic complexity level 的函数，并看到他们在所有不同的代码工作流和决策分支中挣扎；）

【讨论】：

“圈复杂度非常高”...为什么不重构函数并将其分解？即提取方法。而不是仅仅使用 cmets 增加噪音。
@nashwan（写完这个答案9年后）：我同意。尽管我有案例，但并不总是可以重构。看看我最老的问题：stackoverflow.com/q/105852/6309

【解决方案20】：

嗯，总是有“如果你不评论你的代码，我们会找到其他人来评论他们的”的方法。

更温和地告诉他们，他们非常失望如果他们不记录和评论他们正在做的事情，团队。代码不属于个人，除非他们是彻头彻尾的孤狼。它属于团队、群体，无论是公司还是社区。

【讨论】：

【解决方案21】：

“编写代码”=“用特殊语言编写命令序列”+“编写 cmets”

不言而喻在编写代码时注释代码！你有没有评论过已经 3 或 4 个月大的代码？（当然你有，而且除了有趣之外，一切都很好！）

如果您的项目已经有很好的文档记录，那么添加新代码的程序员可能会被激励以类似的方式编写 cmets。

【讨论】：

【解决方案22】：

@James Curran 我 100% 同意！我可以阅读您的代码并弄清楚您告诉编译器做什么；但这并不意味着让编译器这样做是您的意图。我知道我不是一个足够自大的程序员，不会相信每次我编写代码时它都会完全按照我的意图去做。此外，我经常发现它可以帮助我在我的代码中发现愚蠢的逻辑错误，方法是在我编写完代码并尝试解释我打算让代码做什么。

【讨论】：

【解决方案23】：

一个想法是指出每个类写一两句话不到一分钟，每个方法写一个句子不到半分钟。

【讨论】：

这根本不是真的。开发人员可能需要更长的时间才能找到他们正在做的事情的正确人类语言表达，而不是实际编写它。这不是很好地利用时间
如果他们写英文有这么大的困难，那么他们阅读要求就更难了！这是让他们评论他们认为他们在做什么的一个很好的理由。

【解决方案24】：

告诉他们用 Javadoc 注释记录他们的函数和接口，然后通过 Doxygen 运行代码，为他们的代码生成看起来很酷的 HTML 文档。有时，冷静因素可能是一个很好的激励因素。

【讨论】：

【解决方案25】：

我使用了一种微妙的技巧：

我将项目中的警告级别设置为报告为错误。我们的持续集成服务器正在构建整个解决方案以及每次签入时的 XML 文档。

如果开发人员不编写 cmets，则构建失败！之后还要自己写cmets，过一阵子就习惯了。

它在压力方面并不激进，但我发现这是纠正他们行为的好方法。

【讨论】：

强制他们不是很微妙。 :-) 但是如果您开始一个新项目，这可能是一个好主意 - 至少对于 API 等而言。
干得好，您只是强迫开发人员在各处编写大量无意义的 cmets。为什么没有意义？因为如果你强迫某人做他们真的不想做的事情，他们只会滥用它。
你错过了@nashwan 的重点。目标不是玩弄系统和编写无意义的 cmets，而是提醒团队不要忘记编写 cmets。不是他们拒绝写cmets，而是他们没有这样做的习惯。这条规则有所帮助。
“但要提醒团队不要忘记写”问题是您假设更多的 cmets 总是 = 好。
在这种情况下，您是做出假设的人 :) 我的公司有一个明确的公认编码标准 - 每个公共类和方法都应适当记录（XML cmets）。在早期，我们习惯于从中编译出技术文档，因此拥有一个有意义且相关的 cmets 是一件大事。

【解决方案26】：

如果开发人员必须参与代码审查并接触到良好的评论，他们应该能够获得线索。如果他们认为这种做法没有用，那么他们应该从同行评审员那里获得一些反馈。

如果做不到这一点（假设您是主管/经理），请将其作为绩效评估的一部分。如果你能衡量它，你就可以根据它来评估。

确保您评分的评论是经过审查的评论，因为被动攻击型开发者会将每一条最后的陈述都记录为不那么微妙的 FU。

【讨论】：

【解决方案27】：

我已经成为我所谓的 Headrick 规则 的坚定信徒，该规则以我的一位同事的名字命名，他发现激励某人做某事的好方法是让他们感到痛苦不这样做。

在您的情况下，要求您的非评论开发人员花一两个小时来解释他们的代码，也许是对“慢”的观众，也许在他们的午餐时间“避免项目滑点”会大有帮助。聪明的人——即使是顽固的人——学得很快！

【讨论】：

【解决方案28】：

在我看来（我在这里谈论的是 .Net 编程）如果您必须发表评论，那么您就无法使代码可读。答案通常是重构！

但是，如果您觉得必须发表评论，那么它应该始终是“为什么”类型的评论，而不是解释代码功能的评论。

【讨论】：

你将如何重构一个“为什么”的评论？;-)
现在我没这么说;-)

【解决方案29】：

在实际编码之前写下一个方法/类将做什么，这有助于正确处理它 - 您已经对其进行了评论。

【讨论】：

写一个单元测试它应该做什么会更好地利用你的时间

【解决方案30】：

只聘用能确保他们的代码隐含说明意图的优秀工程师（使用 cmets 和其他方式）。任何想要工作的人都必须做正确的事。严酷但公平，恕我直言。

【讨论】：

但是如果他们使用 cmets 那么他们的代码肯定不会隐含（清楚地）说明它的作用吗？毕竟评论不是代码......