我该如何与不喜欢用代码发表评论的团队成员打交道？

我的团队成员之一一直避免在自己的代码中发表评论。

他的代码不是自记录文档，其他程序员很难理解他的代码。

我已经问过他几次以评论他的代码，但是他只是借口或声称他以后会这样做。他担心的是，添加评论将花费太多时间，并会延迟项目。

我可以向他提出什么论据以说服他正确记录他的代码？

关于这一点，我错在专注于代码注释吗？或者这表明应该解决更大的问题吗？

单靠注释并不能提供更好的代码，仅推动“更多注释”可能给您带来的更多好处就是/* increment i by 1 */样式注释。

因此，问问自己自己为什么要这些评论。除非您了解原因，否则“最佳实践”不会被视为争论。

现在，使用注释的最显着原因是使代码更易于理解，当人们抱怨缺少注释时，它们要么是笨拙的鹦鹉，要么就是很难理解正在使用的代码。

因此，不要抱怨缺少注释：抱怨代码不可读。或者更好的是，不要抱怨，只是不断询问有关代码的问题。对于任何您不了解的内容，请询问编写者。无论如何，您应该这样做；使用不可读的代码，您只会问更多问题。而且，如果您稍后返回一段代码，并且不确定自己是否正确地记住了它的功能，请再次询问相同的问题。

如果注释可以解决问题，并且您的同事的大脑运转正常，那么他/她将在某个时候意识到注释代码比让您始终无聊地愚蠢得多。而且，如果您无法提出问题，那么也许该代码已经很容易阅读了，是您有错了-毕竟，并非所有代码都需要注释。

在人际交往能力方面，不惜一切代价避免屈从于居高临下或指责他人；对您的问题要诚实和诚实。

我遇到了很多无法编写自文档代码或有用评论的开发人员。这类人通常缺乏足够的自律或经验来正确地做到这一点。

永远行不通的是，“告诉他们添加更多评论”。这将不会增加他们的自律性或经验。恕我直言，唯一可行的方法是进行频繁的代码审阅和重构会话。开发人员完成任务后，请他/她解释您不理解的代码的任何部分。立即重构或记录代码，以使你们两个月后都能理解。

在几个月的时间内（至少每周两次）执行此操作。如果您足够幸运，其他开发人员将通过这些课程学习，以便您减少审阅频率。

我很惊讶没有人提到代码审查。做代码审查！当他的检查质量不佳时，不要只说“添加评论”。不断问问题，让他告诉您他的代码做什么以及为什么。做笔记。然后，在代码审查的最后，给他一份注释的副本，并告诉他让您的问题相当明显。通过更多注释或仅重构其代码以提高质量（最好是在可能的情况下最好使用后者）

这取决于团队工作人员生成的代码。如果您阅读Bob叔叔的“ 清洁代码”书，您会发现他实际上更喜欢不在代码中添加注释。如果代码本身具有应有的可读性，那么几乎不需要注释。

如果不是这种情况，或者由于某些不可谈判的政策而需要发表评论，那么主要问题就变成是只希望您写评论的是您自己，还是整个团队还是团队/项目领导。如果只有您，那么您应该与其他同事交谈，以了解为什么根本没有什么大不了的。

如果项目负责人缺乏注释，您也可以要求它们作为完整性的一部分，即，如果提交的代码缺乏注释，则工作尚未完成。他可能不会继续做其他工作，直到他当前的工作完成并且需要评论。但是，请记住，这种强制很可能会导致可怕的注释（预期大量糟糕的重复代码注释）。

在我拙见中，唯一可行的方法是讨论您和其他所有人从评论中获得的实际利润。如果他/他不仅仅通过讨论来理解它，那么总是也有困难的方法：与其让他们编写新代码，不如让他们在现有代码上工作。如果可能的话，您应该找到它们两个不同的工作区域-一个带有适当的有用注释，另一个没有注释。必须阅读别人的不可读的未注释代码，这对您自己的工作大开眼界。

我们都去过那里一次，并且为某些工作如此草率的消息的原始作者感到生气。我们每个人都是这样的作者，这是一种额外的反思，使您意识到您应该关注可读性-因此，请不要忘了与同事讨论结果以促进这种反思。

如果您有不能按照指示进行工作的员工，请训斥他，并确保很显然这不会帮助他的职业发展。编码风格的一致性对团队至关重要，如果其他所有人都在写评论，而注释不是，那么这将损害编码风格。

也就是说，您可能可以帮助他。根据我的经验，当有人抗议评论花费太多时间时，就会出现诸如...的心理障碍。

1. 他对自己的代码/设计选择具有自觉性，不希望将它们放在散文中。（代码审查可以帮助提高某人的自信心，甚至可以使他们失望。）
2. 他的工作方式非常线性，没有太大的想法。注释很痛苦，因为它迫使他从工作记忆中卸载即将编写的即时代码，从而以不同的方式构成自己的意图。（如果是这样，则注释对于他的代码质量非常重要。）
3. 历史上人们不理解他的评论。

他们不是：一个程序员认识到的意见是一样的测试是非常重要的只是 -他们是为程序员自己以备将来使用。他们迫使他对他的态度有所不同。

这些都不能替代CI，测试或代码审查。它只是编码的许多关键部分之一，而不是编写代码。

获取代码审查软件，并充分利用它。

我们使用窑炉，我们喜欢它。我们有一个政策，必须对每个变更集进行审查（尽管我们允许开发人员自己对标签和无冲突的合并提出/批准审查（尽管我们大多数人都使用rebaseif）；这样，我们可以快速发现变更集而无需进行审查）。

不清楚的代码是拒绝代码审查的原因。修复程序是注释还是更清晰的代码都没有关系，但是审阅者必须能够理解它。一些开发宁愿重写代码，但其他人（包括我自己）经常发现它更容易表达意见的意图（代码可以轻松地显示它做什么，但它很难显示它应该做的）。

如果对代码的清晰度存在疑问，则审阅者总是胜出。当然，作者理解了，因为他们写了它。它需要别人清楚。

通过使用像Kiln这样的软件，任何变更集都不会被忽略。开发团队中的每个人都非常喜欢这种方式。代码审查软件对我们的代码质量和应用程序质量都产生了巨大影响：-)

初次引入软件时，开发人员很容易对被拒绝的评论表示防御，但是根据我的经验，很快他们就会意识到这种方式会变得更好并接受它:-)

编辑：同样值得注意的是，我们尽量不要让开发人员以口头方式或在评论中的注释中解释隐秘代码。如果不清楚，最好在代码中（在注释中或通过重构）进行解释，然后将新的变更集添加到同一评论中。

有趣的是，应用于自然语言的可读性是通过阅读和理解的速度来衡量的。我猜确实可以采用一个简单的规则，如果特定的代码注释不能改善此属性，则可以避免。

为什么发表评论？

尽管代码注释是嵌入式文档的一种形式，但是高端编程语言中有多种方法可以通过使用语言本身的元素来避免（有意义的代码）多余的“过度文档化”编程。将代码转换为编程教科书中的清单也是个坏主意，在该文本中，几乎以重言式的方式逐字解释了各个语句（请注意已提供的答案中的“ / *将i递增1 * /”），使此类注释有意义仅针对不熟悉该语言的程序员。

尽管如此，它的目的是试图注释真正是“万恶之源”的“文档不足”（但毫无意义）的代码。“文档不足”代码的存在本身就是一个不好的信号-它要么是一个非结构化的混乱，要么是神秘失去目的的古怪黑客。显然，这种代码的价值至少值得怀疑。不幸的是，总是有一些例子，当确实要比将注释包装到新的子例程中时，在一段（视觉分组）格式的代码行中引入注释确实更好（注意“愚蠢的一致性”，即“小头脑的妖精”） 。

代码可读性！=代码注释

可读代码不需要注释注释。在代码的每个特定位置，总是存在该特定代码应该实现的任务的上下文。如果缺少目标和/或代码做了神秘的事情，请不惜一切代价避免它。不允许奇怪的黑客填充您的代码-这是将缺乏时间/兴趣的越野车技术结合起来的直接结果，以了解基础知识。避免在您的项目中使用神秘的代码！

另一方面，可读程序=代码+文档可以包含注释的多个合法部分，例如，以便于生成“ API注释”文档。

遵循代码风格标准

有趣的是，问题不是关于为什么要注释代码，而是关于团队合作-如何以高度同步的方式生成代码（其他所有人都可以阅读/理解）。您是否遵守公司中的任何代码风格标准？它的主要目的是避免编写需要重构的代码，而这些代码过于“个人”和“主观”含糊。因此，我想，如果看到使用代码样式的必要性，那么就有大量严肃的工具来正确实现它-从教育人们到以自动化进行代码质量控制（大量棉绒等）和（修订）控制集成）代码审查系统。

成为代码可读性的传播者

如果您同意阅读代码的次数要多于编写代码的次数。如果清晰地表达思想和思路对您很重要，则无论使用哪种语言进行交流（数学，机器代码或古英语）。如果您的任务是消除枯燥和丑陋的替代思维方式。（对不起） ，最后一个来自另一个“清单”。）提出问题，发起讨论，开始散布发人深省的代码清理书籍（可能不仅类似于Beck的设计模式，而且更像RC Martin已经提到的），解决了歧义。在编程中。进一步介绍了关键思想的要点（引自O'Reilly关于可读性的书）

• 使用适用于每一行代码的技巧来简化命名，注释和格式化
• 优化程序的循环，逻辑和变量，以减少复杂性和混乱
• 在功能级别上的攻击问题，例如重组代码块以一次完成一项任务
• 编写有效，清晰，易读的测试代码

删除“注释”，还有很多（我猜写不需要注释的代码是一项很棒的练习！）。为语义上有意义的标识符命名是一个好的开始。接下来，通过将逻辑连接的操作分组为函数和类来构造代码。等等。一个更好的程序员就是一个更好的作家（当然，假设具备其他技术技能）。

我错在专注于代码注释吗？或者这表明应该解决更大的问题吗？

有些。好的代码不需要注释。但是，正如您所说，他的代码不是自记录文件。因此，我不会专注于评论。您应该专注于提高开发人员的技能和工艺水平。

那么该怎么做呢？Doc Brown关于审阅/重构会议的建议是一个好主意。我发现结对编程更加有效，但是实现起来也可能会困难得多。

首先，我建议您重新处理有关评论的方法。

如果它们是API级别的文档注释（稍后公开），那么该开发人员根本就没有做好自己的工作。但对于其他所有评论，请小心。

在我遇到的大多数情况下，评论都是邪恶的。我建议阅读Robert Martin的“ Clean code”的代码注释一章，以更好地理解原因。

注释以多种方式损害了您的代码：

1）它们很难维护。重构时，您将不得不付出额外的工作；如果您更改注释中描述的逻辑，则也需要编辑注释。

2）他们经常撒谎。您不能信任注释，而必须阅读代码。这就提出了一个问题：您为什么需要这些评论？

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

（哈希不是总和，而是乘积。）

3）注释使代码混乱，很少添加任何值。

我的解决方案：不要添加任何评论，而要完全消除它们！

如果一个团队成员在理解另一个团队成员的代码时有困难（出于任何原因）；那么该团队成员应该能够找出谁是原始代码的编写者（任何明智的版本控制系统），并应被鼓励要求代码的编写者直接对其进行解释（例如，走到办公桌前，坐下来讨论）。

在这种情况下，如果缺少注释是一个问题，那么没有充分注释其代码的人将花费大量时间来解释他们的工作；并且（如果他们很聪明）将开始添加评论，以避免在所有这些解释上花费时间。

注意，出于其他原因，鼓励团队成员互相询问也很有价值。例如，也许一个团队成员经验不足，并且可以向更有经验的团队成员学习。

通常，通过鼓励团队成员互相解释，您可以创建一个自我平衡的系统；在这里，不同的团队成员彼此“自动调整”。

这很大程度上是tdammers答案的扩展，但是要定期执行代码检查。

让他（和其他开发人员）坐下来，仔细阅读他们的代码，或多或少地在上级和同级人员面前防御，将使每个人都成为更好的编码人员，并在相对较短的时间内增加真正的价值。在短期内，它不会给开发人员以任何借口在审查时正确注释其代码。

编辑：我不确定为什么有人会否决我的建议-也许我认为代码审查的好处将是常识...请参阅以下关于实践分析的主题：

代码是否正在审查良好做法？

考虑到通常对评论的极端看法，我犹豫不决。

我要提出的一些论据是，如果您要编写（不可读的）代码，则应对其进行适当的记录？

了解如何编写可维护和可读的代码需要花费时间，实践和经验。缺乏经验的程序员（以及可悲的是，许多经验丰富的程序员）经常遭受宜家效应（PDF）的困扰。那是因为他们构建了它并对其非常熟悉，并且他们确信代码不仅很棒，而且可读性强。

如果这个人是一个优秀的程序员，那么几乎不需要任何文档。但是，大多数程序员都不是很好，他们的许多代码将在“可读性”部门中受苦。让平庸或发展中的程序员“解释他们的代码”是有用的，因为它迫使他们以更为批判的眼光来查看他们的代码。

这是否意味着“记录”他们的代码？不必要。举例来说，过去我有一个类似的程序员遇到这个问题。我强迫他记录下来。不幸的是，他的文档和他的代码一样难以理解，并且没有添加任何内容。回想起来，代码审查会更有帮助。

您（或代表）应与该程序员坐下来，并拉起他的一些旧代码。不是他仅仅通过研究就知道的新东西。您应该要求他以最少的交互引导您完成他的代码。这也可能是一个单独的“文档”会话，他将在其中编写代码来进行解释。然后，他应该获得有关更好方法的反馈。

顺便说一句...无论代码的“可读性”如何好，有时都需要一些文档。API应该具有文档，极其技术性和复杂的操作应该具有文档，以帮助程序员理解所涉及的过程（通常超出了程序员的知识范围），并且诸如复杂的正则表达式之类的东西确实应该记录您要匹配的对象。

许多项目需要代码文档：界面文档，设计文档，...

一些项目要求将此类文档放入代码注释中，并使用Doxygen或Sphinx或Javadoc之类的工具进行提取，以使代码和文档保持更加一致。

这样，开发人员需要在代码中编写有用的注释，并且这项职责已集成到项目计划中。

我将说明大多数答案和评论所暗示的内容：您可能需要在此处找出真正的问题，而不是尝试通过您认为的解决方案。

您有动力看到他的代码中的注释；为什么呢？你说了一个道理；为什么这个原因对您如此重要？他更有动力去做别的事情。为什么呢？他会给出理由；为什么这个原因对他如此重要？重复此过程，直到达到真正引起冲突的程度，然后尝试在那里找到双方都可以接受的解决方案。我敢打赌，这与发表评论几乎没有关系。

如果您遵循良好的编码标准，则将需要最少数量的注释。命名约定很重要。方法名称和变量名称应描述其作用。

我的TL建议我使用较少的评论。他希望我的代码应易于理解和自我描述。简单示例：用于搜索模式的字符串类型的变量名

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

喜欢代码审查的答案，但也许我的过程也会有所帮助。

我喜欢注释，但是几乎从来没有在第一遍将注释添加到代码中。也许这只是我的风格，但是在开发（重构，编写测试等）过程中，我会在同一段代码中碰到3至5次。

每当我感到困惑或有人问我关于一段代码的问题时，我都会尝试对其进行修复，以使其有意义。

这就像添加注释以将混乱的操作集添加到其自己的函数中一样简单，或者可以触发更大的重构，例如提取新对象。

我建议您鼓励小组中的每个人都“拥有”自己的代码对他人可读-这意味着，每当有人问您关于您的代码的问题时，您都承诺做出更改-或更好地与之配对然后进行更改的人！

认真考虑将其作为“团队合同”的一部分（如果没有合同，则要明确创建合同），这样每个人都对此达成了共识，并将其放在墙上的某个地方，这样就可以了。关于您同意做什么的任何问题。

也许这个人需要对良好的编码纪律有所了解，以及为什么其他人能够理解他编写的代码很重要。

在我的职业生涯中，我曾从事过一些真正糟糕的代码库的工作，这些代码库组织得太差，变量名太差，注释太差或根本不存在，以至于代码库损害了我的工作效率。您无法修复或改进您不了解的代码库，并且如果以对新手来说难以理解的方式编写代码库，那么他们将花费更多的时间来尝试理解它，而不是实际工作。

没有比苛刻的经历更好的老师了！

每个代码库中都有一些可怕的隐患，系统的某些部分没人想碰，因为他们害怕破坏某些东西，或者他们无法做任何有意义的工作，因为编写代码的人已经很久了并且已经理解了与他们的代码。如果该代码没有注释并且没有自我记录，那么只会使情况变得更糟。

我建议您找到类似的代码库，并给您麻烦的编码器责任。给他所有权，让他承担责任，让他学习编写无法维护的代码的真正痛苦，因为代码缺乏充分的文档记录或无法在短时间内理解。经过几个月的努力，我相信他会开始出现的。

给他一些没有注释的代码，并请他理解代码。可能是他那时了解适当评论的重要性。

该程序员是否进行一些代码维护。如果不是，他应该：检查您周围是否有任何不受欢迎的项目，并将其维护工作分配给他。

通常，这些都是文档记录不良的项目，您在这些项目上花费了很多时间，试图了解正在发生的事情以进行更正。如果这种经历不使他想要及时更新，那么正确且有用的文档将一无所获。

在我过去的一个项目中，缺少数十条注释（算法，结果或一些基本的JavaDoc），所以我决定为他制作130个问题，每4天通过电子邮件通知每个问题。3周后，他有280期，然后他决定写评论。

评论只有一个目的，只有一个目的：

为什么这段代码会这样做？

如果评论不能解释为什么如此，则应将其删除。使代码混乱的无用注释比无用少，它们是有害的。

我有一种习惯，使自己的评论成为我的IDE中最明显的东西。它们以绿色背景上的白色文本突出显示。真正引起您的注意。

这是因为代码解释什么东西是干什么的，评论是，为什么它是做什么的。我对此不够强调。

一个很好的评论示例：

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

一个不好的例子：

/* instantiate clsUser */

如果将注释用作代码的“部分”：将猛mm方法切成较小的，有用的命名函数，然后删除注释。

如果您在下一行说您在做什么，请执行以下操作：使代码不言自明并删除注释。

如果您将注释用作警告消息：请确保说出原因。

为了补充此处的答案，我可能会添加“如果您要正确完成操作，则必须自己完成。”

我的意思不是成为“首席代码评论员”，而是要成为示范角色，演示您希望其他开发者做什么。他们说表演比讲故事更有效。如果您可以证明高质量注释的好处，甚至可以指导其他开发人员（在他愿意的范围内），那么您可能会在采用代码注释方面找到更多的成功。

同样，在家里，有些琐事我不在乎。然而，那些杂事恰好是我妻子的“小偷小摸”杂事…… 为了使她快乐，必须做的杂事。反之亦然。我认为您可能不得不接受其他开发人员的优先级与您不同，并且不会在所有事情上都与您保持一致。我和我妻子发现的解决方案是，对于那些“小事”，我们只需要自己做，即使这意味着我们要自己做更多的工作。

简单：如果员工未发表评论，则告诉他shift+alt+j在输入代码的同时按每种方法按进行自动评论。请进行代码修订以避免这些问题。