有什么好的论据可以说服他人评论自己的代码？

我注意到，许多程序员更喜欢无注释地编写代码的速度，而宁愿为自己和他人留下一些文档。当我试图说服他们时，我会听到半熟的话，例如"方法/类名应说明其作用"等。我们想对他们说些什么，以改变他们的想法？

如果我们反对发表评论，请留下评论。对于试图说服人们对代码进行注释的人们，这应该是一种资源，而不是其他。 :-)

其他相关问题包括：注释代码，我们是否注释代码以及我们希望如何注释。

解决方案

也许这只是必须从经验中学到的东西。具体来说，就是六个月后返回自己的代码，并试图弄清楚编写代码时我们在想什么(或者我们在做什么)的经验。那肯定使我相信评论并不是一个坏主意。

向他们展示6个月前的代码。如果他们无法在2到4分钟内准确理解并概述其作用，则可能是意思了。

给他们一些(最少约500行)可怕的，未经注释的意大利面条代码以进行重构。确保变量不是逻辑命名的。空格可选。

看看他们如何喜欢它！

过于苛刻，但一口气得到2分。

• 编写好代码。
• 评论它，以便我们和其他人知道它的意思。

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

最后编辑：评论质量也很重要。一些开发人员的工作中代码与注释的比率几乎为2：1，但这并不能使他们获得良好的评价。代码中几乎没有注释，但仍然很有意义。

• 解释你在做什么。不过，代码质量应该可以为我们完成大部分工作。
• 更重要的是，解释一下为什么要做某事！我已经看到了太多的代码，这些代码准确地说明了正在做的事情，而没有一个真正的主意，为什么开发人员(不幸的是，大多数时候我还是这样)首先才认为这是个好主意。

我会说："昨天我必须阅读一些代码。我能够理解它，但少于或者等于5条经过精心选择的注释行，它们解释了它是如何实现其目标的，这使我可以阅读大约一则代码。十次，然后我可能会担心理解一个问题，我并不傻，你也不聪明，因为你可以写一些难以理解的东西，相反，如果你不能写东西可读的文档+代码组合起来，那么我们就不怎么一名开发人员了。"

很久以前，我就已经深思熟虑了：如果我们写了一些东西，但是有能力的人却听不懂，那是错，而不是他或者她的错。这适用于用自然语言编写，也适用于用编程语言编写。

仅注释"为什么"，而不注释"什么"。到目前为止，我同意，应该从类或者方法或者变量名称中清楚地知道它的作用以及用途。重构不引用的地方，而不是评论它。

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

好吧，总有一种"如果我们不注释代码，我们会找其他人注释他们的代码"的方法。
更加温和地告诉他们，如果他们没有记录和评论自己在做什么，他们会感到非常失望。该代码不属于个人，除非它们是完整的独行狼。它属于团队，团队，无论是公司还是社区。

" Writing Code" ="用特殊语言编写命令序列" +" Writing注释"

在编写代码时注释代码是不言而喻的！
我们是否评论了已经使用3或者4个月的代码？ (当然，我们有，除了娱乐之外，其他都没有！)

如果项目已经有充分的文档记录，则可能会激发添加新代码的程序员以类似的方式编写注释。

关于注解也有类似的讨论。这是人们注释代码时遵循的规则之一：关于注释代码的"硬性规则"是什么？一些答案也有很好的理由说明为什么要注释代码。

提醒他们阅读代码只能告诉他们代码的作用，而不是代码的作用。

以身作则。当开发人员看到"正确的事物"时，很容易摇晃，因此看到切实可行的实践可能会鼓励他们做同样的事情。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。....此外，我们可以鼓励小组采用可解决代码可维护性和注释的代码指标。例如，代码分析将为没有摘要文档的方法产生一个错误。

说服一个人的最好方法是使他们自己实现这一目标。使它们调试注释良好的代码。它将向他们显示良好的注释看起来像注释，除非它们真正传达了相关信息(通常是"为什么"，因为代码描述了"什么")，否则它们是无用的。他们会注意到这很容易。然后让他们回到一些旧代码。他们会注意到这有多难。我们不仅向他们展示了不该做什么，而且向他们展示了(这很重要)。我们无需再做任何事情。而且，我们不必尝试通过口头上的方式说服他们。他们只是必须了解以自己的方式注释代码的必要性。当然，这是假设需要注释的代码不是自解释的。

我不是在对你开玩笑，但是你应该改成这样的问题：你如何说服其他开发人员一起工作？

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

如果我们是敏捷团队的成员，则代码是集体所有的，因此，如果我们看到未注释，笨拙或者难以阅读的代码，请继续进行更改(重构)以使我们理解它。如果有人抱怨，请告诉他们为什么，并且要事前准备。我们发现它难以理解，并且没有人拥有该代码。

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

我的想法：

我不会方法/类名应说明其作用。如果不是这样，则说明方法或者类尝试执行过多操作，或者其名称不正确。

我喜欢评论原因，而不是评论。如果不清楚为什么代码使用一种方法而不是另一种方法，请对其进行注释。如果我们必须添加一个hack未使用的变量来解决编译器错误，请说明原因。但是诸如" // Connect to database"之类的注释表明代码错误或者策略错误。名为ConnectToDatabase()的方法要好得多。并且如果其中具有" //确定DB服务器IP"，则应该将其拉到名为" DetermineDbServerIPAddress()"的方法中。

设计可以记录在案，但对于该级别的文献，注释通常是一个糟糕的地方。了解设计知识，并对其中的原因，内容和方式进行一些评论。如果不是，请说服他们改进代码，而不是说服他们评论其代码。

我们还必须在此处区分两个不同的注释：

• API注释(javadoc或者其他类似类型的文档)：我们可以要求它们在极限情况(边界条件，例如空对象或者空字符串或者...)中使用其自己的代码，并查看它们是否真正记住了做什么在这种情况下它们自己的功能(这就是为什么我要使用一个完整的javadoc(包括极限值))
• 内部注释(在源代码内)：我们可以要求他们解释他们已编码的任何函数，只需选择具有非常高的圈复杂度的函数，然后看看他们在所有不同的代码工作流程和决策分支中苦苦挣扎；)

我目前工作的地方当前的编码标准是对每个功能进行注释。像这样空白的规则是有害的，因此永远都不要实行。在某些情况下(某些情况很常见)，添加注释会降低可读性。

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

向上面的代码中添加函数标头有什么意义？我们还要说什么besbes"获取用户名"。并非所有代码都需要注释。我的经验法则是：如果不添加任何功能签名没有提供的有用信息，请跳过注释。

@詹姆斯·柯伦(James Curran)我100％同意！我可以阅读代码并弄清楚我们告诉编译器要执行的操作。但这并不意味着我们要使编译器执行此操作。我知道我不是一个自以为是的程序员，所以我相信每次我写代码时，它所做的事情都与我试图做到的完全一样。此外，我经常发现它可以帮助我在编写代码后仔细检查并试图解释代码的意图，从而在代码中捕获愚蠢的逻辑错误。

一个想法是指出，每个类写一两个句子所需的时间少于一分钟，每个方法写一个句子所需的时间不到半分钟。

告诉他们使用Javadoc注释记录其功能和接口，然后通过Doxygen运行代码以为其代码生成漂亮的HTML文档。凉爽因素有时可能是一个很好的动机。

注释应该详尽，以意图级别(为什么不这样)写，并且很少见。

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

代码应该是自我记录的，并且使用正确的技术，我们可以轻松地获得95％的代码。通常，如果我签入的代码上有任何注释，我认为这是失败的。

在对代码/方法进行实际编码之前写下它会做什么，这对正确执行非常有帮助，我们已经对此进行了评论。

如果我们或者其他开发人员尚未阅读Code Complete(或者Code Complete 2)，则停止我们正在做的事情并阅读它。

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

注释习惯与它们应该描述的代码不同步。结果可能比没有原始评论更糟糕。不仅如此，开发人员还知道评论会老化并且无法被信任。因此，他们将阅读代码并亲自识别出它实际上在做什么！这有点使将评论放在第一位的意义消失了。

话虽这么说，函数名称也可能如此，但它原本可以很好地命名，但是随着时间的推移，已经添加了新的操作，但并未在名称中提及。

所有注释似乎都将开发人员希望放得更近一些的代码分隔开来，以便每个全屏显示更多内容。我知道自己对一段代码的反应，其中包含很多我必须理解的注释。删除所有评论。现在，我可以看到代码的功能。

归根结底，如果我们要花时间做正确的事情，那么时间最好花在重构代码上，以确保代码尽可能合理地自我描述，而不只是编写注释。这样的锻炼可以通过其他方式获得回报，例如识别常见的代码块。

还需要记住的是，许多优秀的开发人员更喜欢编写简洁明快的C＃，Java，而不是具有精确度和歧义性的，不那么精确的人类语言。的确，大多数具有常识的人都知道多少细节就是足够的细节，但是好的开发人员并不是"大多数人"。这就是为什么我们最终得到诸如\向b添加a并将其存储在c中的注释的原因(好的，那太极端了，但是我们明白了)。

要求他们去做他们讨厌做的事情，坦白说不是很擅长(即使我们确信这样做是对的)，这简直就是一场失败的战斗。

我们的策略是进行系统的代码审查，并拒绝未正确记录的代码(通过注释，正确的功能命名和组织等)。如果审稿人不清楚，我们可以回到工作台。

仅聘用能够确保其代码隐式说明意图的优秀工程师(使用注释和其他方法)。任何想要工作的人都必须做对。苛刻，但公平，恕我直言。

我也希望减少评论越多越好，为了使其正常工作，需要明确的简洁代码。所以这就是我从他们开始的地方。告诉他们他们不必发表评论，只要他们编写更好，更清晰的自我评论代码即可。

仅在绝对需要时，不清楚为什么代码正在执行操作时才添加注释。

例如如果我们在十几行代码上方有注释，则只需使用该方法的好名称将其重构为一个方法，或者仅添加注释以取消该方法

我使用一种微妙的技术：

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

如果开发人员不写注释，则构建将失败！
之后，他们必须写评论，所以一段时间后，他们习惯了。

就压力而言，这不是激进的，但我发现这是纠正其行为的好方法。

取决于我们拥有的电量...

我发现一种非常有效的方法是使其成为基于对等体的代码评论点的固定部分。如果有评论说该代码未正确注释，则我会让开发人员对其满意，这基本上意味着他们必须描述足够多的代码，以便我通过打印和阅读来理解。而且我也会这样做。

值得注意的是，这听起来很像狄更斯式，但在开发人员中却很受欢迎。发生了两件事。首先，人们开始评论他们的代码。第二，评论不佳的代码表明开发人员不太了解他们编写的内容(否则他们会描述它)。

唯一的实际缺点是，在针对错误修复等进行修订时，注释必须与代码保持一致。在真正的开发商店中几乎不可能执行此操作，但是一旦确立了足够的良好实践，这种情况自然就会发生。

顺便说一句，我更喜欢代码本身中的注释，而不是陀思妥耶夫斯基小说作为文档字符串。前者是对后续程序员的有用帮助。后者只是很长的过时文本，充满了文档并误导了所有人。

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

少即是多。

强调质量胜于数量。

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

例如：

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

}

我们能想到更大的屏幕空间浪费吗？与阅读没有提供新信息的评论相比，我们能想到更大的脑循环浪费吗？

如果从方法签名中可以明显看出，请不要说！如果我能在几秒钟内找出来，请不要在评论中输入。正如其他人所说的那样，请告诉我为什么选择这样做，而不是做什么。编写代码，以使代码很明显地起作用。

几乎是一个反问。真正好的编码员实际上不需要很多注释。不幸的是，这些珍贵的东西很少。因此，我们要告诉人们，如果没有注释，他们的代码将不可读。

程序员几乎没有足够的时间完成漂亮的工作。似乎我们总是急于要进行单元测试，以查看它是否会开始吐出结果。因此，我的最终答案是找到一个工作环境，使普通程序员有时间提高质量。我，我已经两次向Google提出申请，但两次遭到拒绝。

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

如果失败(假设我们是主管/经理)，则将其作为他们绩效评估的一部分。如果可以测量，则可以基于它进行评估。

确保我们在此评论上获得好评，因为积极进取的开发人员会将每条最后的陈述记录为不那么微妙的FU。

在十年的发展中，我从未见过这样的评论，它实际上告诉了我一些有关代码的有用信息。注释通常是过时的或者显而易见的。一旦编写它们，就需要维护另一件事。我认为要注释的唯一合理的事情是正则表达式或者汇编代码。

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

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

在情况下，要求不加评论的开发人员花一两个小时向"慢"的听众解释他们的代码，也许是在午餐时间"避免项目延误"，这将是很长的路要走的。聪明的人-甚至是固执的人-快点学习吧！

尽管可以很好地使用注释来提供对代码的深入了解，但我认为，鼓励程序员编写描述性代码比留下注释更有价值。最终，使用冗长的注释来解释本来可以编写的代码，最终使用清晰的名称和签名编写较小的方法将为我们提供更好的服务。

令人遗憾的事实是，绝大多数程序员只有在遇到不良文档的另一端时，才会正确地注释其代码。坚持维护缺乏明确评论的应用程序真是太糟糕了。通常在此之后(IME)，在代码流中进行注释。

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

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

还向他们展示诸如SandCastle之类的优势。

" blabla评论为什么不blabla"

对于有关注释代码的每个问题，一个简单的答案...我的问题是每个人都在谈论"为什么"和"什么"，就像每次对每个人都是同一件事一样。

显然不是这样。当我发现一些新东西(一个API，一个框架，一个新项目，一个工具...)时，有很多事情我不了解，或者甚至不知道它的存在。但是一段时间之后，很多事情变得更加有意义。我不会迷失在代码丛林中以了解类的用途。

首先，"为什么"和"什么"是同一件事，可以将此事总结为"？"。
在花了一些时间来学习和理解之后，"内容"变得越来越容易掌握，最终变得如此明显，以至于我什至忘记了它的存在。随着"什么"变得"更清晰"，我的思想有了更多的资源来问自己"为什么"，并且我对整个体系结构的理解也越来越完整。

如果我在学习的开始就在代码中添加了注释，即使我试图注释"为什么"，我也会注释那些更有经验的人已经认为显而易见的东西(他们将其称为"什么"并说出注释)是没有用的)。
在经历了更大的学习曲线浪潮之后撰写的评论将数量减少，并且将描述所评论事物的非常特定的特征(只有那些达到这种理解水平的人才能理解)。

关于这件事的最后一件事是：我从来没有浪费时间阅读评论，它们常常减少了我的学习时间。我从未见过"评论过多"的代码。我经常阅读对我(像每个人)都没有用的评论，但我从未想过"如果我一直都花这些时间阅读评论，做点更有用的事情！"。鉴于所有现代IDE都提供了可以隐藏大注释的ui，我不明白为什么写无用注释可能被认为是不好的。

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

我更喜欢在代码的明显部分中使用无用的注释，而不是在15页长的深色方法中什么都不做...。

我认为(并且我在这里谈论的是.Net编程)，如果我们必须发表评论，则会使代码可读性失败。答案通常是重构！

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