Question

说服别人评论他们的代码有什么好的理由？

我注意到许多程序员喜欢编写代码的速度，而没有评论为自己和其他人留下一些文档。当我试图说服他们时，我会听到一半被烘焙的东西，比如“方法/班级名称应该说它做什么”等等。你会怎么说他们改变主意？

如果您反对评论，请发表评论。对于试图说服人们评论代码的人来说，这应该是一种资源，而不是其他。： - ）

其他相关问题包括：Commenting code，Do you comment your code和How would you like your comments。

Answer 1

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

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

Answer 2

从6个月前开始显示他们自己的代码。如果他们无法理解并在2到4分钟内准确概述它的作用，那么你的观点可能已经完成了。

Answer 3

我的意见：

我不会。方法/类名应该说明它的作用。如果没有，那么方法或类都试图做得太多，或者它的命名很差。

我喜欢评论为什么，而不是什么。如果不清楚为什么代码使用一种方法而不是另一种方法，请对其进行评论。如果你不得不添加一个黑客未使用的变量来解决编译器错误，请注释原因。但是像“//连接数据库”这样的评论是代码错误或政策不好的迹象。名为ConnectToDatabase（）的方法要好得多。如果它中有“//确定数据库服务器IP”，那么应该将其拉出到名为“DetermineDbServerIPAddress（）”的方法。

可以记录设计，但对于该级别的文档，评论通常是一个不好的地方。有了设计知识，以及对原因的评论，应该是什么以及如何应该是显而易见的。如果不是，而不是说服他们评论他们的代码，让他们改进它。

Answer 4

也许这只是必须从经验中学到的东西;特别是，六个月后回到你自己的代码的经验，并试图找出你在写它时你在想什么（或你在做什么）。这当然让我确信评论并不是一个坏主意。

Answer 5

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

了解他们的喜欢方式！

过于苛刻，但它一次性得到两分。

写好您的代码。
对此进行评论，以便 和其他人 知道这意味着什么。

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

最后一次编辑：评论质量也非常重要。一些开发人员在他们的工作中具有几乎2：1的代码与注释比率，但这并不能使他们成为好评。你的代码中可能会有很少的评论，但仍然有很多意义。

解释你在做什么。您的代码质量应为您完成大部分工作。
更重要的是，解释你为什么要做某事！我已经看到了很多代码，这些代码确切地说明了某些事情正在做什么并且没有真正的想法为什么开发人员（不幸的是我大部分时间）都认为这是一个好主意。

Answer 6

提醒他们阅读代码只能告诉他们代码做什么，而不是所谓的做什么。

Answer 7

如果您或其他开发人员尚未阅读代码完成（或Code Complete 2），请停止正在执行的操作并阅读它。

有一点值得注意的是“一个功能应该只做一件事并且做得好”。当这样一个函数以一件事命名时，它还能做什么进一步需要评论？

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

虽然说一个函数名称也是如此，但它可能已经被命名为原始名称，但加时间新的操作已被添加到名称中未提及。

所有评论似乎都将开发人员希望更接近的代码行分开，以便他们可以在每个屏幕上看到更多。我知道自己对一段代码的重新操作有很多我必须理解的评论。删除所有评论。现在我可以看到代码是什么了。

在一天结束的时候，如果你要花时间做正确的事情，那么花在修改代码上的时间要好得多，以确保它可以合理地自我描述，而不仅仅是写作评论。这样的练习可以通过其他方式获得回报，例如识别常见的代码块。

值得注意的是，许多优秀的开发人员更喜欢编写清晰的C＃，Java，而不是那些精确度低得多的人类语言，并且具有所有的假设和含糊之处。大多数具有常识的人都会知道细节有多少是足够的细节，但优秀的开发人员不是“大多数人”。这就是为什么我们最终得到像\\adds a to b and store it in c这样的评论（好吧，这太过极端，但你明白了。）

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

Answer 8

我会说“昨天我必须阅读你的一些代码。我能够理解它但是不到或等于5条精心挑选的评论解释如何完成它的目标将允许我阅读它在大约十分之一的时间里，我可能会担心理解一个问题。我不是傻瓜，你也不聪明，因为你可以写出难以理解的东西。相反，如果你能不会产生可读的文档+代码集合，那么你就不再是开发人员了。“

我很久以前就把这个钻进了我的脑海里：如果你写了一些东西而且有合理能力的人无法理解，那就是你的错，而不是他或她的错。这适用于用自然语言书写，它适用于用编程语言编写。

Answer 9

我们的策略是进行系统的代码审查，并拒绝未正确记录的代码（通过评论，正确的功能命名和组织等）。如果评论者不清楚，你会回到工作台上。

Answer 10

我对你并不嗤之以鼻，但你应该将问题改为你如何说服其他开发者团队合作？

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

如果您是敏捷团队的一员，代码是集体拥有的，那么当您看到未注释，笨拙或难以阅读的代码时，请继续并更改（重构）它以便您理解它。如果有人抱怨，请告诉他们为什么并提前做好准备。你发现它不可理解，没有人拥有代码。

Answer 11

关于评论也有过类似的讨论。以下是评论代码时人们遵循的规则：What are your "hard rules" about commenting your code?。一些答案也有很好的理由说明为什么要对代码进行评论。

Answer 12

在你的评论欲望中显示智慧，他们更有可能倾听。

少即是多。

强调质量而非数量。

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

例如：

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

}

你能想到更大的屏幕空间浪费吗？您是否可以想到更多的脑循环浪费而不是阅读没有提供新信息的评论？

如果方法签名很明显，请不要说出来！如果我能在几秒钟内搞清楚，请不要将其放在评论中。正如其他人所说，告诉我为什么你选择这样做，而不是你做了什么。编写代码，使其显而易见。

Answer 13

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

Answer 14

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

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

代码应该是自我记录的，使用right techniques，您可以很容易地获得95％的代码。一般来说，如果我签到的代码中仍有任何注释，我认为这是一个失败。

Answer 15

取决于你拥有多少力量......

我发现一种非常有效的方法是将其作为基于同行的代码审查的固定部分 - 评论要点。如果有人评论说代码被严重评论，我会让开发人员对它表示满意，这基本上意味着他们必须通过打印并阅读它来描述足够的代码以便我理解它。我也会这样做。

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

唯一真正的缺点是，当修改错误修复等时，评论必须与代码保持同步。这几乎不可能在真正的开发商店中执行，但是一旦足够好的做法被刻上了它排序自然而然地发生了。

BTW我更喜欢代码本身的评论而不是Dostoevsky小说作为文档字符串。前者对后续程序员有用。后者只是一段很长的过时文本，填补了文档并误导了所有人。

Answer 16

我目前工作的当前编码标准是评论每个功能。像这样的空白规则是有害的，永远不应该到位。有些情况（其中一些是常见的）添加注释会消除可读性。

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

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

Answer 17

以身作则。当他们看到正确的东西时，开发人员很容易受到影响，所以看到可靠的实践行动可能会鼓励他们做同样的事情。此外，您可以鼓励您的小组采用代码指标来解决代码可维护性和注释问题。例如，代码分析将为没有摘要文档的方法生成错误。

Answer 18

您还必须在此处区分两个不同的评论：

API评论（javadoc或其他类似文档）：您可以要求他们 use their own code in a limit scenario （边界条件，如空对象或空字符串或...），看看他们是否真的设法记住在这种情况下他们自己的功能（这就是为什么我是完整的javadoc，包括限制值）
内部评论（在源代码中）：您可以让他们解释他们编码的任何函数，只需选择一个 的函数{{3 }} ，看到他们围绕所有不同的代码工作流程和决策分支进行斗争;）

Answer 19

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

Answer 20

@James Curran我100％同意！我可以阅读你的代码并找出你告诉编译器要做的事情;但这并不意味着你打算让编译器这样做。我知道我不是一个足够程度的程序员，相信每次我编写代码都会让我完全按照我的努力去做。另外，我经常发现，在我编写代码并试图解释我打算为代码做什么之后，我会在代码中发现愚蠢的逻辑错误。

Answer 21

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

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

Answer 22

我已成为我称之为 Headrick's Rule 的坚定信徒，以我的同事的名字命名，他发现激励某人做某事的好方法是让他们感到痛苦< em>不去做。

在您的情况下，要求您的非评论开发人员花一两个小时来解释他们的代码，也许是为了“慢”的观众，也许在他们的午餐时间“避免项目滑点”将会有很长的路要走。聪明的人 - 即使是顽固的人 - 快速学习！

Answer 23

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

如果失败（假设您是主管/经理），那就将其作为绩效评估的一部分。如果你可以测量它，你可以根据它进行评估。

确保这是你评分的评论，因为被动攻击性开发者会将每一句话都记录为一个不那么微妙的FU。

Answer 24

嗯，总是有“如果你不评论你的代码，我们会找到其他人评论他们的方法”。
更温和，告诉他们他们非常放松如果他们没有记录和评论他们正在做什么，那么他们就会进入团队。代码不属于个人，除非他们是完全孤独的狼。它属于团队，团队，无论是公司还是社区。

Answer 25

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

在编写代码时对进行评论将是不言而喻的！你有没有评论已经3或4个月大的代码？（当然，你有，但其他一切都很有趣！）

如果您的项目已经有详细记录，那么添加新代码的程序员可能会以类似的方式撰写评论。

Answer 26

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

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

如果开发人员不写评论，则构建失败！之后，他们必须写评论，所以过了一会儿，他们就习惯了。

在压力方面并不积极，但我发现这是纠正行为的好方法。

Answer 27

告诉他们使用Javadoc通知记录他们的函数和接口，然后通过Doxygen运行代码，为他们的代码生成看起来很酷的HTML文档。凉爽因素有时可能是一个很好的动力。

Answer 28

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

Answer 29

只有当你不确定代码正在做它正在做的事情时，才会在你绝对需要时添加注释。

e.g。如果您有十几行代码的注释，那么只需使用方法的好名称重构为方法，或者只是添加注释以使用该方法

Answer 30

我也在更少评论的阵营中，为了实现这一点，它需要清晰简洁的代码。所以这就是我从他们开始的地方。告诉他们他们不必评论，只要他们写出更好，更清晰，自我评论的代码。

Answer 31

只雇用优秀的工程师，确保他们的代码隐含地表明意图（使用评论和其他方式）。任何想要工作的人都必须做得对。苛刻，但公平，恕我直言。

Answer 32

几乎是一个修辞问题。真正优秀的程序员实际上并不需要很多评论。不幸的是，这些中很少有。因此，您告诉人们，如果没有评论，他们的代码将无法读取。

程序员几乎没有足够的时间做一份漂亮的工作。似乎我们总是急于得到一些单元测试，以确定它是否会开始吐出结果。因此，我的最终答案是找到一个具有氛围的工作场所，使普通程序员有时间获得质量。我，我已经两次申请Google并被拒绝了两次。

Answer 33

在实际编码之前写下一个方法/类将会做什么有助于实现它的正确性 - 并且你已经对它进行了评论。

Answer 34

我从未在十年的发展过程中看到一条评论，它实际上告诉了我一些关于代码的有用信息。评论通常是过时的或明显的。一旦你写下它，还有一件事需要维护。我认为唯一合理的评论是正则表达式或汇编程序代码。

如果您需要评论，则需要将您想要评论的内容提取到单独的方法或类中。记录代码的另一种方法是编写测试。

Answer 35

虽然评论可以很好地用于提供对代码的深入了解，但我认为鼓励程序员编写描述性代码比留下评论更有价值。使用清晰的名称和签名编写较小的方法最终将为您提供更好的服务，而不是漫长的漫无边际的评论，这些评论解释了本来可以写得更好的代码。

Answer 36

令人遗憾的是，绝大多数程序员都不会正确评论他们的代码，直到他们最终出现在糟糕文档的另一面。被困在维护缺乏明确评论的应用程序是非常糟糕的。通常就在那之后（IME），代码流中的注释。

是的，这件事发生在我身上，我现在彻底评论。

Answer 37

我还认为向开发人员展示好评的重要性的最佳方式是向他展示自己过去的代码。

同时向他们展示SandCastle之类的优势。

Answer 38

“blabla评论为什么不是什么blabla”

关于评论代码的每一个问题都是一个简单的答案......我的问题是每个人都在谈论“为什么”和“什么”，因为他们每次都对每个人都是一样的。

显然情况并非如此。当我发现新的东西（API，框架，新项目，工具......）时，有很多我不理解的东西，或者我甚至都不知道它的存在。但过了一段时间，很多事情变得更有意义。我不必在代码丛林中迷失自己，以了解课程的用途。

首先，“为什么”和“什么”是相同的东西，这个东西可以概括为“？”。花了一些时间学习和理解后，“什么”变得越来越容易掌握，最后变得如此明显，我甚至忘记了它的存在。随着“什么”变得“更清晰”，我的思维有更多的资源来问自己“为什么”，我对整个架构的理解变得越来越完整。

如果我在学习开始时在代码中添加评论，即使我试图评论“为什么”我会评论更有经验的人已经认为明显的东西（他们会称之为“什么”和说评论没用）。在更大的学习曲线浪潮之后撰写的评论将会更少，并且描述评论事物的一个非常具体的特征（只有达到这种理解水平的人才能理解）。

最后一件事是：我从来没有浪费时间阅读评论，而且他们经常缩短我的学习时间。我从未见过“太过评论”的代码。我经常阅读对我没有用的评论（像每个人一样），但我从未想过“如果我只花了所有这些时间阅读评论做更有用的事情！”。鉴于所有现代IDE都能提供隐藏大评论的事实，我不明白为什么写一篇无用的评论会被认为是不好的。

从更主观的角度来看，我更喜欢在一个代码页中看到一些无用的绿色单词，而不是在空白色背景上缩进的几个单词。

我更喜欢在一个明显的代码部分中使用无用的注释而不是15页长的黑暗方法....

Answer 39

不确定为什么所有其他答案都在谈论“说服”程序员写评论。对于动物和儿童，我们使用正面强化，但对于成年人，我们使用逻辑，就像它起作用（它没有）。

每次他们写评论时给他们一个cookie - 例如，一个真正的cookie，或一个“伟大的男人” - 并看看它是如何工作的。如果必须的话，总是因不写评论而受到惩罚。当然，你不必成为惩罚的老板：公众嘲笑，轻蔑和一般排斥都是足够强大的技巧。

如何说服人们评论他们的代码

39 个答案: