有什么好的论据可以说服其他人评论他们的代码？
我注意到许多程序员更喜欢在没有注释的情况下编写代码的感知速度，而不是为自己和他人留下一些文档。当我试图说服他们时，我会听到半生不熟的东西，比如“方法/类名应该说明它的作用”等。你会对他们说些什么来改变他们的想法？
如果您反对评论，请留下评论。对于试图说服人们评论代码的人来说，这应该是一种资源，而不是其他方式。:-)
hstoerr
问问题
3656 次
39 回答
48
只评论“为什么”而不是“什么”。到目前为止，我同意，应该从类或方法或变量名称中清楚它的作用和用途。重构它没有而不是评论它。
如果你采用这种方法，你会得到评论，你会得到有用的评论。程序员喜欢解释他们为什么要做某事。
于 2008-10-01T20:45:53.673 回答
30
向他们展示他们自己 6 个月前的代码。如果他们无法在 2 到 4 分钟内准确理解和概述它的作用，那么您的观点可能已经提出。
于 2008-10-01T20:43:21.667 回答
30
我的意见：
我不会。方法/类名应该说明它的作用。如果没有，要么方法或类试图做太多事情，要么命名不当。
我喜欢评论为什么，而不是什么。如果不清楚为什么代码使用一种方法而不是另一种方法，请评论它。如果您必须添加一个 hack 未使用的变量来解决编译器错误，请评论原因。但是像“//连接到数据库”这样的注释是错误代码或错误策略的标志。名为 ConnectToDatabase() 的方法要好得多。如果它有“//Determine DB server IP”，也许应该把它拉到一个名为“DetermineDbServerIPAddress()”的方法中。
设计可以记录在案，但是对于该级别的文档来说，注释通常是一个糟糕的地方。有了设计知识，以及一些关于为什么、什么和如何应该是显而易见的评论。如果不是，与其说服他们评论他们的代码，不如让他们改进它。
于 2008-10-01T20:51:10.553 回答
17
也许这只是必须从经验中学习的东西；具体来说，六个月后回到你自己的代码，并试图弄清楚你在写代码时到底在想什么（或者你在做什么）的经历。这当然让我相信评论并不是一个坏主意。
于 2008-10-01T20:43:16.627 回答
13
给他们一些（至少约 500 行）可怕的、未注释的意大利面条代码来重构。确保变量没有逻辑命名。空格可选。
看看他们有多喜欢它！
过于苛刻，但它一口气得到两分。
- 写好你的代码。
- 评论它，以便您和其他人知道它的含义。
我应该强调，这段代码不应该来自他们。注释对于理解你自己的代码非常有用，几个月后，它们对于理解其他人代码的复杂部分也非常重要。他们需要了解其他人可能必须了解他们在做什么。
最后一个编辑：评论质量也很重要。一些开发人员在他们的工作中拥有几乎 2:1 的代码与评论比率，但这并不能使他们成为好的评论。你的代码中可以有非常少的注释，但它仍然很有意义。
- 解释你在做什么。不过，您的代码质量应该为您完成大部分工作。
- 更重要的是，解释你为什么要做某事！我已经看到了很多代码，它们准确地说明了某事正在做什么，却不知道为什么开发人员（不幸的是，大多数时候是我）首先认为这是一个好主意。
于 2008-10-01T20:43:22.413 回答
12
提醒他们阅读代码只能告诉他们代码做了什么，而不是它应该做什么。
于 2008-10-01T20:48:17.207 回答
9
如果您或其他开发人员尚未阅读 Code Complete（或Code Complete 2），请停止您正在做的事情并阅读它。
突出的一件事是“一个函数应该只做一件事并且做得很好”。当这样一个函数以它做得好的一件事命名时，还有什么需要评论的？
注释有与他们应该描述的代码不同步的习惯。结果可能比没有原始评论更糟糕。不仅如此，开发人员还知道评论可能会老化并且不可信。因此，他们将阅读代码并自己辨别它实际上在做什么！这有点抵消了将评论放在首位的意义。
话虽如此，函数名称也是如此，它可能最初命名得很好，但名称中未提及的超时新操作已添加到其中。
所有评论似乎都将开发人员希望更靠近的代码行分开，以便他们可以在每个屏幕上看到更多内容。我知道我自己对一段代码的反应，其中有很多我必须理解的注释。删除所有评论。现在我可以看到代码是什么。
归根结底，如果你要花时间把事情做好，你的时间最好花在重构代码上，以确保它尽可能合理地自我描述，而不是仅仅写评论。这样的练习以其他方式获得了回报，例如识别常见的代码块。
值得牢记的是，许多优秀的开发人员更喜欢编写清晰干净的 C#、Java，而不是那些具有所有假设和歧义的不太精确的人类语言。确实，大多数有常识的人都会知道多少细节才是足够的细节，但优秀的开发人员并不是“大多数人”。这就是为什么我们最终会得到这样的评论\\adds a to b and store it in c（好吧，这太极端了，但你明白了）。
要求他们做他们讨厌做的事情，坦率地说，他们不太擅长（即使你确信这是正确的做法）只是一场已经失败的战斗。
于 2008-10-01T21:19:37.133 回答
6
我会说“昨天我不得不阅读你的一些代码。我能够理解它，但少于或等于 5 行精心挑选的解释它如何实现其目标的评论将使我能够阅读它大约一-第十次，然后我可能会担心理解一个问题。我不傻，你也不聪明，因为你可以写一些难以理解的东西。相反，如果你不会产生可读的文档+代码集合，那么您就不是开发人员了。”
我很早以前就被灌输过：如果你写了一些东西，而一个有合理能力的人看不懂，那是你的错，而不是他或她的错。这适用于自然语言的写作，也适用于编程语言的写作。
于 2008-10-01T20:44:35.127 回答
6
我不是在对你刻薄，但你应该将问题改写为如何说服其他开发人员作为一个团队工作？
说真的，有些人认为你可以读懂他们的想法。
如果您是敏捷团队的一员，代码是集体所有的，因此当您看到未注释、笨拙或难以阅读的代码时，请继续更改（重构）它，以便您理解它。如果人们抱怨，请告诉他们原因并坦诚相告。你发现它难以理解，并且没有人拥有代码。
于 2008-10-01T20:49:21.247 回答
6
我们的策略是进行系统的代码审查，并拒绝没有正确记录的代码（通过注释、正确的函数命名和组织等......）。如果审阅者不清楚，你就回到工作台，期间。
于 2008-10-01T21:20:29.300 回答
5
关于评论也有类似的讨论。以下是人们在评论代码时遵循的规则：关于评论代码，您的“硬性规则”是什么？. 一些答案也有很好的理由说明你想要评论你的代码。
于 2008-10-01T20:48:15.243 回答
4
说服一个人的最好方法是让他们自己意识到这一点。让他们调试注释良好的代码。它将向他们展示好的评论是什么样的——除非他们真正传达了相关的信息（通常是“为什么”，因为代码描述了“什么”），否则评论是没有用的。他们会注意到它是多么容易。然后让他们回到他们的一些旧代码。他们会注意到这有多难。您不仅向他们展示了不该做什么，还向他们展示了该做什么（这更重要）。你不必再做任何事情了。更重要的是，您不必尝试口头说服他们。他们只需要了解以自己的方式注释代码的必要性。这当然是假设需要注释的代码不是自我解释的。
于 2008-10-01T20:49:14.817 回答
4
在您对评论的渴望中表现出智慧，他们将更有可能倾听。
少即是多。
强调质量而不是数量。
在我的团队中，有人推动评论某些 API 中的所有内容。一些开发人员开始使用一种工具，该工具可以通过查看方法名称和签名来自动生成注释。
例如：
/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{
}
你能想出更大的屏幕空间浪费吗？你能想到比阅读没有提供新信息的评论更浪费大脑周期吗？
如果从方法签名上看出来了，就不要说了！如果我能在几秒钟内弄清楚，请不要将其放在评论中。正如其他人所说，告诉我你为什么选择这样做，而不是你做了什么。编写您的代码，以便它的作用一目了然。
于 2008-10-02T00:02:14.853 回答
3
以身作则。当开发人员看到正确的事情时，他们很容易动摇，所以看到实际的实践可能会鼓励他们做同样的事情。此外，您可以鼓励您的团队采用解决代码可维护性和注释的代码指标。例如，代码分析将为没有摘要文档的方法产生错误。
于 2008-10-01T20:48:43.633 回答
3
我目前工作地点的当前编码标准是注释每个函数。像这样的空白规则是有害的，永远不应该存在。在某些情况下（其中一些很常见）添加注释会降低可读性。
class User {
getUserName() { /* code here */ }
}
在上面的代码中添加函数头有什么意义？你还要说什么 besdies“获取用户名”。并非所有代码都需要注释。我的经验法则是：如果您没有添加函数签名没有的任何有用信息，请跳过注释。
于 2008-10-01T20:53:27.757 回答
3
评论应该是彻底的，在意图的层面上写的（为什么不怎么写），而且很少见。
在编写代码时，我理所当然地倾向于合理地大量评论。然后，我回过头来尝试删除尽可能多的注释，而不会降低代码的可理解性。> 80% 的时间这就像提取一个命名良好的方法一样容易，这通常会导致注释只是复制代码本身中的信息。除此之外，如果有一段代码“需要”注释，我会寻找简化它或使其更清晰的方法。
代码应该是自我记录的，使用正确的技术，你可以很容易地完成 95% 的工作。一般来说，如果我签入的代码上还有任何注释，我认为这是失败的。
于 2008-10-01T21:08:34.240 回答
3
就看你有多大的力量了...
我发现一个非常有效的方法是让它成为基于同行的代码审查的固定部分——评论点。如果有评论说代码被错误地注释了，我会让开发人员对它进行满意的评论，这基本上意味着他们必须描述足够多的代码，以便我通过打印和阅读来理解它。我也会这样做。
值得注意的是，这在开发人员中很受欢迎，尽管这听起来像是狄更斯式的。发生了两件事。首先，人们开始评论他们的代码。其次，糟糕的注释代码成为开发人员不太理解他们所写内容的标志（否则他们会描述它）。
唯一真正的缺点是，在修改代码以进行错误修复等时，注释必须与代码保持同步。这在真正的开发商店中几乎不可能强制执行，但是一旦根深蒂固了足够的良好实践，它就会自然而然地发生.
顺便说一句，我更喜欢代码本身中的注释，而不是陀思妥耶夫斯基小说作为文档字符串。前者对后来的程序员很有帮助。后者只是一长段过时的文本，填满了文档并误导了所有人。
于 2008-10-01T22:35:08.543 回答
2
让他们使用不熟悉的 API，但在未连接 Internet 的机器上进行编程（如果你现在可以找到他们的话），这样他们就无法访问 API 文档。如果他们试图使用非文档人员的代码，这实际上是他们强迫其他开发人员做的事情！
于 2008-10-01T20:49:51.650 回答
2
您还必须在这里区分两个不同的评论：
API 注释（javadoc 或其他类似类型的文档）：您可以要求他们在限制场景中使用自己的代码（边界条件，如空对象或空字符串或......），看看他们是否真的能记住什么在这种情况下他们自己的功能
（这就是为什么我要一个完整的 javadoc 包括 limit-value）内部评论（在源代码中）：您可以要求他们解释他们编写的任何函数，只需选择一个具有非常高的圈复杂度级别的函数，然后看看他们在所有不同的代码工作流和决策分支中挣扎；）
于 2008-10-01T20:53:03.687 回答
1
好吧，总是有“如果你不评论你的代码，我们会找到其他人来评论他们的”的方法。
更温和地告诉他们，如果他们不记录和评论他们正在做的事情，他们会让团队非常失望。代码不属于个人，除非他们是彻头彻尾的孤狼。它属于团队、群体，无论是公司还是社区。
于 2008-10-01T20:47:34.213 回答
1
“编写代码”=“用特殊语言编写命令序列”+“编写注释”
写代码的时候注释一下是不言而喻的！你有没有评论过已经 3 或 4 个月大的代码？（当然你有，除了有趣之外，一切都是如此！）
如果您的项目已经有很好的文档记录，那么添加新代码的程序员可能会被激励以类似的方式编写注释。
于 2008-10-01T20:48:14.697 回答
1
@James Curran 我 100% 同意！我可以阅读您的代码并弄清楚您告诉编译器做什么；但这并不意味着让编译器这样做是您的意图。我知道我不是一个足够自大的程序员，不会相信每次我编写代码时它都会完全按照我的意图去做。此外，我经常发现它可以帮助我在我的代码中发现愚蠢的逻辑错误，方法是在我编写完代码并尝试解释我打算让代码做什么。
于 2008-10-01T20:56:39.527 回答
1
一个想法是指出，每节课写一两句话不到一分钟，每个方法写一个句子不到半分钟。
于 2008-10-01T21:03:39.307 回答
1
告诉他们用 Javadoc 注释记录他们的函数和接口，然后通过 Doxygen 运行代码，为他们的代码生成看起来很酷的 HTML 文档。有时，冷静因素可能是一个很好的动力。
于 2008-10-01T21:04:06.017 回答
1
我使用一种微妙的技术：
我将项目中的警告级别设置为报告为错误。我们的持续集成服务器正在构建整个解决方案以及每次签入时的 XML 文档。
如果开发人员不写评论，构建失败！在那之后，他们必须写评论，所以过了一段时间，他们就习惯了。
它在压力方面并不激进，但我发现这是纠正他们行为的好方法。
于 2008-10-01T22:18:07.273 回答
1
如果开发人员必须参与代码审查并接触到良好的评论，他们应该能够获得线索。如果他们不认为这种做法有用，那么他们应该从同行评审员那里获得一些反馈。
如果做不到这一点（假设您是主管/经理），则将其作为绩效评估的一部分。如果你能衡量它，你可以根据它来评估。
确保它是您评分的评论评论，因为被动攻击性开发人员会将每一个最后的陈述记录为不那么微妙的 FU。
于 2008-10-02T01:57:19.337 回答
1
我已经成为我所谓的 Headrick 规则的坚定信徒，该规则以我的一位同事的名字命名，他发现激励某人做某事的好方法是让他们不做这件事感到痛苦。
在你的情况下，要求你的非评论开发人员花一两个小时来解释他们的代码，也许是对“慢”的观众，也许在他们的午餐时间“避免项目滑点”会有很长的路要走。聪明的人——即使是顽固的人——学得很快！
于 2008-11-03T02:19:34.403 回答
1
在我看来（我在这里谈论的是 .Net 编程）如果您必须发表评论，那么您无法使代码可读。答案通常是重构！
但是，如果您觉得必须添加注释，那么它应该始终是“为什么”类型的注释，而不是解释代码功能的注释。
于 2010-05-26T11:06:46.287 回答
0
在实际编码之前写下一个方法/类将做什么，这对正确处理它有很大帮助——而且你已经评论过它。
于 2008-10-01T21:08:50.857 回答
0
只雇用优秀的工程师，确保他们的代码隐含地说明意图（使用注释和其他方式）。任何想要工作的人都必须做正确的事。苛刻，但公平，恕我直言。
于 2008-10-01T21:29:36.640 回答
0
我也属于评论越少越好的阵营，为了让它发挥作用，它需要清晰简洁的代码。所以这就是我要从他们开始的地方。告诉他们他们不必评论，只要他们写出更好、更清晰、自我评论的代码。
于 2008-10-01T21:34:55.677 回答
0
仅在绝对需要时才添加注释，当不清楚为什么代码在做它正在做的事情时。
例如，如果您在十几行代码之上有注释，那么只需使用该方法的好名称重构为一个方法，或者只是在该方法上方添加注释
于 2008-10-01T22:09:02.130 回答
0
几乎是一个反问。真正优秀的程序员实际上不需要太多评论。不幸的是，这些东西很少。因此，您是在告诉人们，如果没有注释，他们的代码将无法阅读。
程序员几乎没有足够的时间来完成漂亮的工作。似乎我们总是急于得到一些东西进行单元测试，看看它是否会开始吐出结果。所以我最终的答案是找到一个工作场所，它的氛围能让普通程序员有时间关注质量。我，我向谷歌申请了两次，两次被拒绝。
于 2008-10-02T01:42:18.263 回答
0
在十年的开发中，我从未见过真正告诉我有关代码的有用信息的评论。评论通常是过时的或陈述显而易见的。一旦您编写它们，就需要维护它们。我认为唯一合理的评论是正则表达式或汇编代码。
如果您需要评论，您可能需要将想要评论的内容提取到单独的方法或类中。记录代码的另一种方法是编写测试。
于 2008-11-03T01:46:24.470 回答
0
虽然评论可以很好地用于提供对代码的洞察力，但我认为鼓励程序员编写描述性代码比留下评论更有价值。编写具有清晰名称和签名的较小方法最终将比冗长的评论解释本可以更好地编写的代码最终为您提供更好的服务。
于 2008-12-24T14:32:19.560 回答
0
一个可悲的事实是，绝大多数程序员不会正确地注释他们的代码，直到他们最终陷入糟糕的文档的另一端。被困在维护一个缺乏清晰评论的应用程序是很糟糕的。通常紧随其后（IME），代码流中的注释。
是的，这发生在我身上，我现在彻底评论。
于 2008-12-24T14:39:11.650 回答
0
我还认为向开发人员展示好的评论有多重要的最好方法是向他展示他自己过去的代码。
也向他们展示像 SandCastle 这样的东西的优势。
于 2009-01-08T12:15:45.057 回答
0
“blabla评论为什么不是什么blabla”
每个关于注释代码的问题的简单答案......我的问题是每个人都在谈论“为什么”和“什么”，就像他们每次对每个人来说都是一样的。
显然不是这样。当我发现新事物（API、框架、新项目、工具……）时，会有很多我不理解的东西，或者我什至不知道它的存在。但一段时间后，很多事情变得更有意义。我没有迷失在代码丛林中去理解类的用途。
起初，“为什么”和“什么”是同一个东西，这个东西可以概括为“？”。经过一段时间的学习和理解，“什么”变得越来越容易掌握，最终变得如此明显，以至于我什至忘记了它的存在。随着“是什么”变得“更清晰”，我的脑海里就有更多的资源去问自己“为什么”，我对整个架构的理解也越来越完整。
如果我在学习开始时在代码中添加评论，即使我试图评论“为什么”，我也会评论更有经验的人已经认为显而易见的内容（他们会称之为“什么”并说出评论没用）。跨越较大的学习曲线波之后写的评论将在数量上减少，并且描述被评论事物的一个非常具体的特征（只有达到这种理解水平的人才能理解）。
最后一点是：我从来没有浪费时间阅读评论，而且他们经常减少我的学习时间。我从未见过“评论过多”的代码。我经常阅读对我无用的评论（就像每个人一样），但我从未想过“如果我一直花时间阅读评论做一些更有用的事情！”。鉴于所有现代 IDE 都提供了能够隐藏大评论的 ui，我不明白为什么写一个无用的评论会被认为是不好的。
从更主观的角度来看，我更喜欢在一页代码中看到一些无用的绿色单词，而不是在空白背景上缩进的几个单词。
我更喜欢在代码的明显部分添加无用的注释，而不是在 15 页长的黑暗方法中没有任何注释......
于 2009-11-23T20:34:05.280 回答
0
不知道为什么所有其他答案都在谈论“说服”程序员写评论。对于动物和儿童，我们使用正强化，但对于成年人，我们使用逻辑，好像它有效（它不起作用）。
每次他们写评论时给他们一个cookie——例如，一个真正的cookie，或者一个“很棒的人”——看看它是如何工作的。如果必须，总是会因为不写评论而受到惩罚。当然，你不必成为老板来惩罚：公开嘲笑、蔑视和普遍排斥是足够强大的技术。
于 2011-02-02T18:15:14.440 回答