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

#1 楼

仅凭注释并不能带来更好的代码，仅推动“更多注释”可能就给您带来比/* increment i by 1 */样式注释更多的东西。除非您了解原因，否则“最佳实践”不会被视为一个论点。注释，它们要么是笨拙的鹦鹉，要么很难理解正在使用的代码。

所以不要抱怨缺少注释：抱怨代码不可读。或者更好的是，不要抱怨，只是不断询问有关代码的问题。对于您不了解的任何内容，请询问编写者。无论如何，您都应该这样做。使用不可读的代码，您只会问更多问题。而且，如果稍后再返回一段代码，并且不确定自己是否正确地记住了它的功能，请再次提出相同的问题。 ，他/她将在某个时候意识到，注释代码比让您一直无休止地询问愚蠢的问题容易得多。而且，如果您无法提出问题，那么也许该代码已经很容易阅读了，这是您的错-毕竟，并非所有代码都需要注释。 ，不惜一切代价避免屈从于屈辱或指责；对您的问题要诚实和诚实。

#2 楼

我遇到了很多开发人员，他们在编写自文档代码或有用的注释时遇到了麻烦。这类人通常缺乏足够的自律或经验来正确地做到这一点。这将不会增加他们的自律性或经验。恕我直言，唯一可行的方法是进行频繁的代码审阅和重构会话。开发人员完成任务后，请让他/她解释您不理解的代码的任何部分。立即重构或记录代码，以使你们两个月后都能理解。

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

#3 楼

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

#4 楼

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

如果不是这种情况，或者由于某些不可协商的政策而需要注释，则主要问题在于，是否只有您要他/她发表评论，还是整个团队还是团队/项目负责人。如果只是您，那么您应该与其他同事交谈，以找出为什么根本没什么大不了的事情。完整性，即，如果提交的代码缺少注释，则工作尚未完成。他可能不会继续做其他工作，直到他当前的工作完成并且需要评论。但是，请记住，这种强制很可能会导致可怕的注释（期望大量糟糕的重复代码注释）。您和其他所有人从评论中获得的实际利润。如果他/他不能仅仅通过讨论来理解它，那么总也有困难的方法：与其让他们编写新代码，不如让他们在现有代码上工作。如果可能的话，您应该找到它们两个不同的工作区域-一个带有适当的有用注释，另一个没有注释。必须阅读别人的不可读的未注释代码，这对您自己的工作大开眼界。

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

#5 楼

如果您的员工无法按照指示进行操作，请训斥他，并确保很显然这不会帮助他的职业发展。编码风格的一致性对团队至关重要，如果其他所有人都在写评论，而注释不是这样，那将会损害编码风格。以我的经验，当有人抗议评论花费太多时间时，就会遇到诸如...


的心理障碍。散文散布。 （代码审查不仅可以帮助破坏别人的自信心，还可以帮助他们破坏信心。）
他的工作方式非常线性，没有太大的想法。注释很痛苦，因为它迫使他从工作记忆中卸载即将编写的即时代码，从而以不同的方式构成自己的意图。 （如果是这样，注释对于他的代码质量非常重要。）
从历史上看，人们不理解他的注释。它们不仅供将来使用，而且还供程序员自己使用。他们迫使他对他的方法有所不同。

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

#6 楼

获取代码审查软件，并将其很好地使用。

我们使用Kiln，并且喜欢它。我们有一项政策，必须对每个变更集进行审查（尽管我们允许开发人员自己对标签和无冲突的合并提出/批准审查（尽管我们大多数人都使用rebaseif）；这样，我们可以快速发现变更集而无需审查）。 br />
代码不清晰是拒绝代码审查的原因。修复是注释还是更清晰的代码都没有关系，但是审阅者必须能够理解它。一些开发人员更喜欢重写代码，但其他开发人员（包括我自己）通常会发现更容易在注释中表达意图（代码可以轻松显示其功能，但很难显示其功能）。 >如果对代码的清晰度存在疑问，则审阅者总是胜出。当然，作者理解了，因为他们写了它。它需要别人清楚。

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

开发人员在初次引入该软件时很容易对被拒绝的审查进行防御，但是根据我的经验，它并没有他们花了很长时间才意识到这种方式会更好，并接受它：-)

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

#7 楼

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

为什么要注释？作为嵌入式文档的一种形式，高端编程语言有多种方法可以通过使用语言本身的元素来避免（有意义的代码的）多余的“过度文档化”编程。将代码转换为编程教科书中的清单也是个坏主意，在该文本中，几乎以重言式的方式逐字解释了单个语句（请注意已提供的答案中的“ / *将i递增1 * /”），使此类注释有意义但是，仅是试图注释真正是“万恶之源”的“文档不足”（但毫无意义）的代码。 “文档不足”代码的存在本身就是一个不好的信号-它要么是无组织的混乱，要么是神秘的迷失了目的的古怪黑客。显然，这种代码的价值至少值得怀疑。不幸的是，总是有一些例子，当确实要比将注释包装到新的子例程中时，在一段（视觉分组）格式的代码行中引入注释确实更好（注意“愚蠢的一致性”，即“小头脑的妖精”） 。

代码可读性！=代码注释

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

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

遵循代码样式标准

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

成为代码可读性的传播者

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


通过适用于每一行的提示简化命名，注释和格式设置代码
重新定义程序的循环，逻辑和变量，以减少复杂性和混乱性
在功能级别上遇到攻击问题，例如重组代码块以一次执行一项任务编写有效，简洁的有效测试代码，以及易于理解的

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

#8 楼

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


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

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

#9 楼

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

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

在我遇到的大多数情况下，评论都是邪恶的。我建议阅读罗伯特·马丁（Robert Martin）的“干净代码”的代码注释一章，以更好地理解原因。
注释以几种方式损害了您的代码：很难维护。重构时，您将不得不付出额外的工作；如果您更改注释中描述的逻辑，则也需要编辑注释。

2）它们通常是说谎的。您不能信任注释，而必须阅读代码。这就引出了一个问题：为什么您完全需要这些注释？ > 3）注释使代码混乱，并且很少添加任何值。

我的解决方案：与其添加更多注释，不如完全消除它们！

评论

---

这真是愚蠢。我希望没有人相信如此糟糕的评论风格会有所帮助。但是，您诚实地认为不应使用评论吗？

– jmk
13年2月16日在22:27

---

是的，这是一个愚蠢的建议，如果代码的可读性令人难以置信，我可以理解很少的注释，但是看到注释应该说明该方法的作用，以及到达多个类后将在哪里使用该方法没有理由不发表意见，他们可以帮助所有人。

– DBlackborough
13年2月17日，0：56

---

要记住的重要一点是，尽管现在一切对您都有意义，但其他人将不得不在三年内维护您的代码。不要拧过来。

–xaxxon
2013年2月17日在2:32

---

@xaxxon更不用说那个苹果了，即使那个人可能是你。

–蓬松
2013年2月17日3:00，

---

@mehaase-不是什么，不是怎么做，但是为什么是在代码中添加注释的最重要原因。

–汉克·兰格维德
13年2月26日在21:38

---

#10 楼

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

在这种情况下，如果缺少注释是一个问题，那么没有充分注释其代码的人将花费大量时间来解释他们的工作；并且（如果他们很聪明）将开始添加评论，以避免在所有这些解释上花费时间。例如，也许一个团队成员经验不足，可以向经验丰富的团队成员学习。在这里，不同的团队成员可以彼此“自动调整”。

#11 楼

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

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

编辑：我不确定为什么有人会拒绝我的建议-也许我理所当然地认为代码审查的好处是常识...请参阅此线程以了解实践的社区分析：

#12 楼

考虑到通常对评论的极端看法，我犹豫不决。话虽如此...编写应该正确记录的（不可读的）代码？


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

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

这是否意味着“记录”他们的代码？不必要。举例来说，过去我有一个类似的程序员遇到这个问题。我强迫他记录下来。不幸的是，他的文档和他的代码一样难以理解，并且没有添加任何内容。回想起来，代码回顾会更有用。不是他仅仅通过研究就知道的新东西。您应该要求他以最少的交互引导您完成他的代码。这也可以是一个单独的“文档”会话，他将在其中编写代码来进行解释。然后他应该获得关于更好方法的反馈。

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

#13 楼

许多项目需要代码文档：接口文档，设计文档，...

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

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

#14 楼

我要说明大多数答案和评论所暗示的内容：您可能需要在此处找出真正的问题，而不是尝试通过提出的解决方案来实现。在他的代码中；为什么？你说了一个道理；为什么这个原因对您如此重要？他更有动力去做别的事情。为什么？他会给出理由；为什么这个原因对他如此重要？重复此过程，直到达到真正引起冲突的水平，然后尝试在那里找到双方都可以接受的解决方案。我敢打赌，它与评论无关。

#15 楼

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

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

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

#16 楼

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

我喜欢注释，但是我几乎从不将注释第一次添加到代码中。也许这只是我的风格，但在开发过程中（重构，编写测试等），我会在同一段代码中碰到3到5次。关于一段代码，我尝试对其进行修复，以使其有意义。就像提取一个新对象一样。

我建议您鼓励小组中的每个人都“拥有”自己的代码对他人可读，这意味着每次有人问您有关您代码的问题时，您承诺进行更改-或更好地与该人结对，然后立即进行更改！您没有一个）-这样，每个人都对此达成了共识，然后将其放在墙上的某个地方，这样就不会对您有什么疑问了您已经同意这样做。

#17 楼

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

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

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

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

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

#18 楼

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

#19 楼

该程序员是否进行一些代码维护。如果不是，那么他应该：检查您周围是否有任何不受欢迎的项目，并将其分配给他。可能很容易纠正。
如果这种经历不能使他想要最新的信息，那么正确和有用的文档将一无所获。

#20 楼

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

#21 楼

注释只有一个目的，只有一个目的：

为什么此代码执行此操作？应该删除。使代码变得混乱的无用注释比无用少，它们实际上是有害的。它们以绿色背景上的白色文本突出显示。确实会引起您的注意。

这是因为代码说明了正在执行的操作，而注释则说明了执行该操作的原因。我对此不够强调。

一个很好的注释示例： />

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

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

如果在说下一行的操作：使代码不言自明并删除注释。

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

#22 楼

为了补充这里的答案，我可能会添加“如果您想正确地做就必须自己做。”演示您希望其他开发人员执行的操作。他们说表演比讲故事更有效。如果您可以证明高质量注释的好处，甚至可以指导其他开发人员（在他愿意的范围内），那么您可能会发现在代码注释采用方面取得了更大的成功。我不愿意做的琐事。然而，那些杂事恰好是我妻子的“小偷小摸”杂事……为了使她开心，必须做的杂事。反之亦然。我认为您可能不得不接受其他开发人员的优先级与您不同，并且不会在所有事情上都与您保持一致。我和我妻子发现的解决方案是，对于那些“小偷小摸”的琐事，我们只需要自己做，即使这意味着我们自己要做更多的工作。

#23 楼

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