如何说服人们评论他们的代码
说服别人评论他们的代码有什么好的理由？
我注意到很多程序员都喜欢编写代码的速度，而没有留下任何留给自己和其他人的文档的意见。 当我试着说服他们的时候，我会听到一些半熟的东西，比如“方法/class级名称应该说出来”等等。你会怎样改变他们的想法？
如果您反对评论，请留下评论。 这应该成为人们试图说服人们评论代码的资源，而不是其他方式。 🙂
其他相关的问题是： 评论代码 ， 你评论你的代码 ， 你如何评论你的意见 。
说服一个人的最好方法就是让他们自己去实现。 让他们debugging好评论代码。 它会告诉他们什么样的评论是好的 – 除非他们真正传达相关信息（通常是“为什么”，因为代码描述了“什么”），评论是没有用的。 他们会注意到它是多么容易。 然后让他们回到一些旧的代码。 他们会注意到它有多难。 你不仅向他们展示了不该做什么，而且要做什么（这更重要）。 你不必再做了。 更重要的是，你不必尝试口头说服他们。 他们只需要了解需要以自己的方式评论代码。 这当然是假设需要评论的代码不是自我解释的。
只评论“为什么”，而不是“什么”。 到目前为止，我同意，从类或方法或variables名称中应该清楚它的作用和用途。 重构，而不是评论它。
如果你采取这种方法，你会得到意见，你会得到有用的意见。 程序员喜欢解释为什么他们在做什么。
从6个月前向他们展示他们自己的代码。 如果他们在2到4分钟内不能理解和确切地说明它的作用，那么你的观点可能已经被提出来了。
我的想法：
我不会。 方法/类名称应该说明它做了什么。 如果不是这样，那么这个方法或者类就是试图做太多，或者它的命名不好。
我是评论为什么，而不是什么的粉丝。 如果不清楚为什么代码使用另一种方法，请对其进行评论。 如果你不得不添加一个黑客未使用的variables来解决编译器错误，请评论为什么。 但是像“//连接到数据库”这样的注释是错误的代码或不好的策略。 名为ConnectToDatabase（）的方法要好得多。 如果它有“/ /确定数据库服务器的IP”，也许应该拉出一个名为“DetermineDbServerIPAddress（）”的方法。
devise可以被logging下来，但是评论对于这个级别的文档通常是一个糟糕的地方。 有了devise的知识，以及为什么，一些评论应该是显而易见的。 如果不是，而不是说服他们评论他们的代码，让他们改进它。
也许这只是从经验中学习的东西; 特别是在六个月后回到自己的代码的经验，并试图弄清楚当你写这些代码时你在想什么（或者你在干什么）。 这当然使我确信评论并不是一个坏主意。
给他们一些（〜500行，最低限度）可怕的，未注释的意大利面代码来重构。 确保variables不是逻辑上的命名。 空白可选。
看看他们怎么样！
过于苛刻，但一口气得到两点。
- 写好你的代码。
- 评论它，让你和其他人知道这意味着什么。
我应该强调，这个代码不应该来自它们。 评论对于理解你自己的代码是非常有用的，几个月后，但对于理解其他人的代码的复杂部分也是很重要的 。 他们需要了解别人可能需要了解他们在做什么。
最后一个编辑：评论质量也是非常重要的。 一些开发者在他们的工作中几乎有2：1的代码 – 评论比率，但是这并不能使他们评论得很好。 你可以在你的代码中有惊人的评论，但是它仍然有很大的意义。
- 解释你在做什么 。 你的代码质量应该为你做这个工作的大部分。
- 更重要的是，解释你为什么要做点什么 ！ 我已经看到了很多代码，说明了什么是做什么，没有真正的想法，为什么开发人员（不幸的是我大部分时间）认为这是一个好主意。
提醒他们，阅读代码只能告诉他们代码是干什么的，而不是干什么。
如果您或其他开发人员还没有阅读Code Complete（或Code Complete 2 ），那么请停止正在进行的操作并阅读它。
有一点比较突出的是“一个function应该只做一件事，做得好”。 当这样一个function被命名为一件事情之后，它还有什么需要进一步的评论呢？
评论有与他们应该描述的代码不同步的习惯。 结果可能比原先的评论还糟糕。 不仅如此，开发人员也知道评论可能会老化，不能被信任。 因此，他们会阅读代码，并为自己辨别它究竟在做什么！ 这样做的意义在于把评论放在第一位。
话虽如此，function名称也可能是真实的，但它可能已经很好地命名为原始的，但join新的操作已被添加到名称中没有暗示。
所有评论似乎都将开发人员希望彼此靠得更近的代码分离开来，以便他们可以在每个屏幕上看到更多的代码。 我知道我自己对一段代码的重新行动，有很多我必须理解的评论。 删除所有评论。 现在我可以看到代码是什么了。
在这一天结束的时候，如果你花时间把事情做好，你的时间花在重构代码上要好得多，以确保它的合理性，而不仅仅是写评论。 这样的练习能够以其他方式获得回报，例如识别常见的代码块。
值得铭记的是，许多优秀的开发人员更喜欢写清晰的C＃，Java，而不是那些不太精确的人类语言，只要他们具有所有的假设和含糊之处。 真正的大多数具有常识的人会知道多less细节是足够的细节，但好的开发人员不是“大多数人”。 这就是为什么我们最终得到的评论像\\adds a to b and store it in c （确定这太极端，但你明白了）。
要求他们做一些他们讨厌的事情，而坦率地说他们并不擅长（即使你确信自己做的是正确的事情）只是一场已经失去的战斗。
我对你并不嗤之以鼻，但是你应该改变这个问题， 你怎么说服其他开发者作为一个团队工作？
严重的是，有些人认为你可以阅读他们的想法。
如果你是一个敏捷团队的一员，代码是集体拥有的，所以当你看到未注释，尴尬或难以阅读的代码时，请继续改变（重构）代码，以便理解它。 如果有人抱怨，告诉他们为什么，并提前。 你发现它是不可理解的，没有人拥有代码。
我们的策略是进行系统的代码审查，并拒绝没有正确logging的代码（通过评论，正确的function命名和组织等）。 如果审稿人不清楚的话，可以回到工作台上。
我会说“昨天我必须读一些你的代码，我能够理解它，但是不到5条精心挑选的解释如何实现它的目标的线将允许我在大约一然后我可能会担心理解一个问题，我不是愚蠢的，你不聪明，因为你可以写出难以理解的东西，相反，如果你不能生产可读的文档+代码集合，那么你不是一个开发人员。“
我很久以前就钻了这个东西：如果你写了一些东西，而一个有能力的人不能理解，那么这是你的错，而不是他的错。 这适用于使用自然语言编写，它适用于编程语言编写。
关于评论也有类似的讨论。 以下是评论代码时人们遵循的规则：关于评论代码的“硬性规则”是什么？ 。 一些答案也有很好的理由，你为什么要评论你的代码。
expression你的意见的智慧，他们将更倾向于倾听。
less即是多。
强调质量而非数量。
在我的团队中，有人推动评论某些API的一切。 一些开发人员开始使用一种工具，通过查看方法名称和签名来自动生成评论。
例如：
/// <summary> /// Gets the Person. /// </summary> /// <returns> /// A Person /// </returns> public Person GetPerson() { }
你能想到更大的屏幕房地产浪费吗？ 你能想到比阅读没有提供新信息的评论更大的脑循环浪费吗？
如果从方法签名可以看出来，不要说了！ 如果我能在几秒钟内弄清楚，不要把它放在评论中。 正如其他人所说的，告诉我为什么你select这样做，而不是你做了什么 。 编写你的代码，以便明白它的作用。
以身作则。 开发人员在看到“正确的事物”时很容易被动摇，所以看到可靠的实践行为可能会鼓励他们也这样做。 此外，您可以鼓励您的小组采用代码度量标准来解决代码可维护性和评论问题。 例如，代码分析会为没有摘要文档的方法产生一个错误。
评论应该是彻底的，意图层面（为什么不怎么样），而且很less见。
在编写代码时，我倾向于合理地评论，理所当然。 然后，我回过头去尝试删除尽可能多的评论，而不会降低代码的可理解性。 > 80％的时间，这是一样容易提取一个有名的方法，这通常会导致一个注释，只是重复代码本身的信息。 除此之外，如果有一段“需要”评论的代码，我会寻找方法来简化它或使之更加清晰。
代码应该是自我logging的，使用正确的技巧可以很容易地获得95％的方法。 通常我认为这是一个失败，如果有任何意见留在代码，我检查。
取决于你有多大的权力…
我发现一个非常有效的方法是使其成为基于对等的代码评论的固定部分 – 评论点。 如果有人说这个代码是不好评论的话，我会让开发人员评论一下我的满意度，这基本上意味着他们必须通过打印和阅读来描述足够的代码才能理解它。 而且我也会这样做。
引人注目的是，尽pipe它听起来像狄更斯，但它仍然深受开发者的欢迎。 发生了两件事。 首先，人们开始评论他们的代码。 其次，严重评论的代码成为开发人员不太了解他们所写的内容（否则他们会描述的）。
唯一真正的缺点是，在修改错误修正等问题时，这些注释必须跟上代码。这在一个真正的开发商店中几乎是不可能实现的，但是一旦有足够的好习惯被固化，它就会自然发生。
顺便说一句，我喜欢在代码本身的意见，而不是陀思妥耶夫斯基小说作为文档string。 前者对后来的程序员是一个有用的帮助。 后者只是一个过时的文本，填补了文档和误导每个人的很长一段文字。
让他们使用不熟悉的API，但在非互联网连接的计算机上进行编程（如果这些日子您可以find它们），以便他们无法访问API文档。 这实际上是他们迫使其他开发者如果试图使用非文档的代码所做的！
你也必须在这里区分两个不同的评论：
-
API注释 （javadoc或其他类似的文档）：您可以要求他们在极限情况下使用自己的代码 （边界条件，如空对象或空string或…），看看他们是否真的设法记住什么在这种情况下他们自己的职能
（这就是为什么我是一个完整的javadoc包括限制值 ） -
内部注释 （在源代码中）：你可以让他们解释他们已经编码的任何函数，只要select一个具有非常高的圈复杂度的函数，看看他们围绕着所有不同的代码工作stream程和决策分支;
那么，总是有“如果你不评论你的代码，我们会发现别人会评论他们的”方法。
更温和地告诉他们，如果他们没有logging和评论他们在做什么，他们会严重地放弃队伍。 代码不属于个人，除非他们是完全孤独的狼。 它属于团队，无论是公司还是社区。
目前我的工作地点的编码标准是评论每个function。 这样的空白规则是有害的，应该永远不会到位。 有些情况下（和其中一些常见的），添加注释会消除可读性。
class User { getUserName() { /* code here */ } }
在上面的代码中添加一个函数头是什么意思？ 还有什么要说besdies“获取用户名”。 不是所有的代码都需要评论。 我的经验法则是：如果你没有添加function签名没有的有用信息，跳过注释。
“编写代码”=“用特殊语言编写命令序列”+“编写评论”
在写代码的时候评论代码是不言而喻的！ 你有没有评论已经3或4个月的代码？ （当然你有，其他的一切都很有趣！）
如果你的项目已经被很好地logging下来，那么添加新代码的程序员可能会被激励以类似的方式写评论。
我使用一种微妙的技术：
我将项目中的警告级别设置为错误报告。 而且我们的持续集成服务器正在构build整个解决scheme以及每个cckck-in中的XML文档。
如果开发人员不写评论，则构build失败！ 之后，他们必须写评论，所以过了一段时间，他们已经习惯了。
在压力方面它没有侵略性，但我觉得它是纠正自己行为的好方法。
@James Curran我100％同意！ 我可以阅读你的代码，找出你告诉编译器做的事情; 但这并不意味着你的意图是让编译器这样做。 我知道我不是一个足够的程序员，相信每次我写代码的时候，我都会这样做。 另外，我经常发现，通过在写完代码之后，通过阅读代码来解决我想要的代码，我可以发现它可以帮助我捕捉愚蠢的逻辑错误。
一个想法是指出，每个class级写一两句话，不到半分钟的时间，每种方法写一个句子只需不到一分钟的时间。
告诉他们用Javadoc commments来logging他们的函数和接口，然后通过Doxygen运行代码来为他们的代码生成一个很酷的HTML文档。 有时酷的因素可能是一个很好的激励因素。
如果开发者不得不参与代码评论，并且接触到好的评论，他们应该能够得到线索。 如果他们不认为这种做法有用，那么他们应该从同行评审员那里得到一些反馈。
如果没有（假设你是主pipe/经理）将其作为绩效评估的一部分。 如果你能测量它，你可以根据它来评价。
确保这是评分评论，因为被动积极的开发者会将每一个最后的陈述logging为不那么细微的FU。
我已经坚定地相信我所谓的“ 头脑里的规则” （ Headrick Rule） ，他以我的一位同事的名字命名，他发现激励某人做某事的好方法是让他们不要做这件事。
在你的情况下，要求你的非评论开发人员花一两个小时解释他们的代码，或许是为了“慢”观众，也许在午餐时间“避免项目延误”将会有很长的路要走。 聪明的人 – 即使是固执的人 – 快速学习！
“blabla评论为什么不是什么blabla”
每个关于评论代码的问题都是一个简单的答案…我的问题是每个人都在谈论“为什么”和“什么”，每个人每次都是一样的。
显然不是这样。 当我发现新的东西（一个API，一个框架，一个新的项目，一个工具……）时，有很多东西我不明白，或者我甚至不知道存在。 但是过了一段时间，很多事情变得更有意义了。 我不想在密码丛林中迷失自我，去理解什么是课堂。
起初，“为什么”和“是什么”是一回事，这个东西可以概括为“？”。 花了一些时间去学习和理解后，“什么”变得越来越容易把握，最终变得如此明显，甚至忘记了它的存在。 随着“什么”变得越来越“清晰”，我的脑海里有了更多的资源来问自己“为什么”，而我对整个build筑的理解也越来越完整。
如果我在学习时间开始的时候在代码中join评论，即使我试图评论“为什么”，我会评论更有经验的人已经认为是明显的（他们会称之为“什么”，并说评论是无用的）。 在学习曲线的大浪之后写的评论数量会减less，并且描述评论事物的一个非常具体的特征（只有那些已经达到这个理解水平的人才能理解）。
最后一件事是：我从来没有浪费时间阅读评论，他们经常减less我的学习时间。 我从来没有见过“太评论”的代码。 我经常阅读那些对我无用的评论（像大家一样），但是我从来没有想过“如果我只是花时间阅读评论，做些更有用的事情！”。 鉴于所有现代IDE提供了可以隐藏大量评论的事实，我不明白为什么写一个无用的评论可能被认为是不好的。
从更主观的angular度来看，我更喜欢在一页代码中看到一些无用的绿色单词，而不是在空白的白色背景上缩进的几个单词。
我更喜欢在一个明显的代码部分没有用的评论，而不是在一个15页长的黑暗方法中没有任何评论….
在我看来（如果你不得不提出一个评论，你不能使代码可读），我在这里讨论.Net编程。 答案通常是重构！
但是，如果您觉得您必须提出意见，那么它应始终是“为什么”types的评论，而不是解释代码所做的解释。
在实际编写代码之前写下一个方法/类将做什么有助于很好地实现 – 而且你已经评论了它。
