如何说服人们的评论，他们的代码[封闭]
https://stackoverflow.com/questions/159597
-
03-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian解决方案
说服一个人的最好方法就是让他们自己意识到这一点。让他们调试好评论的代码。它将向他们展示什么是好的评论 - 评论是没有用的，除非他们真正传达相关信息（通常是“为什么”，因为代码描述了“什么”）。他们会注意到它是多么容易。然后让他们回到他们的一些旧代码。他们会注意到它有多难。你不仅要向他们展示不该做什么，而且要做什么（这更重要）。你不必再做了。更重要的是，你不必试图口头说服他们。他们必须理解以自己的方式评论代码的必要性。当然，这是假设需要评论的代码不能自我解释。
其他提示
只评论“为什么”而不是“什么”。到目前为止，我同意，从类或方法或变量名称应该清楚它的作用和用途。重构而不是评论它。
如果采用这种方法，您将获得评论，您将获得有用的评论。程序员喜欢解释他们为什么要做某事。
从6个月前开始显示他们自己的代码。如果他们无法理解并在2到4分钟内准确概述它的作用，那么你的观点可能已经完成了。
我的意见：
我不会的。方法/类的名称应该说它做什么。如果没有，要么是方法或类想做太多了，或者是名为很差。
我的粉丝评论为什么，没什么。如果它不清楚为什么代码是使用一种方法在另一，评论。如果你不得不添加一个黑客未使用的可变要获得围绕一个编译错误，意见的原因。但评论似"//连接数据库"迹象的糟糕代码或坏的政策。一种名为ConnectToDatabase()要好得多。如果它有"//确定数据库服务器IP"在这，也许应该被拉出一种名为"DetermineDbServerIPAddress()".
设计可以记载，但是意见是一个一般较差的地方，为这一水平的文件。与知识的设计，和一些评论为什么，什么，以及如何应该是显而易见的。如果不是这样，而不是说服他们要评论他们的代码，让他们改善。
也许这只是必须从经验中学到的东西;特别是，六个月后回到你自己的代码的经验，并试图找出你在写它时你在想什么（或你在做什么）。这当然让我确信评论并不是一个坏主意。
给他们一些（约500行，最少）可怕的，未注释的意大利面条代码来重构。确保变量没有逻辑命名。空白可选。
了解他们的喜欢方式！
过于苛刻，但它一次性得到两分。
- 写好您的代码。
- 对此进行评论，以便 和其他人 知道这意味着什么。
- 解释你在做什么。您的代码质量应为您完成大部分工作。
- 更重要的是，解释你为什么要做某事！我已经看到了很多代码，这些代码确切地说明了某些事情正在做什么并且没有真正的想法为什么开发人员（不幸的是我大部分时间）都认为这是一个好主意。
我应该强调这段代码不应该源于它们。评论 对于理解您自己的代码非常有用，几个月后，但它们对于理解其他人的代码的复杂部分也非常重要。他们需要了解其他人可能必须了解他们正在做什么。
最后一次编辑：评论质量也非常重要。一些开发人员在他们的工作中具有几乎2：1的代码与注释比率，但这并不能使他们成为好评。你的代码中可能会有很少的评论，但仍然有很多意义。
提醒他们阅读代码只能告诉他们代码做什么，而不是所谓的做什么。
如果您或其他开发人员尚未阅读Code Complete（或 Code Complete 2 ），请停止你正在做并阅读它。
有一点值得注意的是“一个功能应该只做一件事并且做得好”。当这样一个函数以一件事命名时，它还能做什么进一步需要评论？
评论的习惯是与他们应该描述的代码不同步。结果可能比没有原始评论更糟糕。不仅如此，开发人员知道评论可能会老化且无法信任。因此，他们将阅读代码并自己辨别它实际上在做什么！这样就无法将评论放在首位。
虽然说一个函数名称也是如此，但它可能已经被命名为原始名称，但加时间新的操作已被添加到名称中未提及。
所有评论似乎都将开发人员希望更接近的代码行分开，以便他们可以在每个屏幕上看到更多。我知道自己对一段代码的重新操作有很多我必须理解的评论。删除所有评论。现在我可以看到代码是什么了。
在一天结束的时候，如果你要花时间做正确的事情，那么花在修改代码上的时间要好得多，以确保它可以合理地自我描述，而不仅仅是写作评论。这样的练习可以通过其他方式获得回报，例如识别常见的代码块。
值得注意的是，许多优秀的开发人员更喜欢编写清晰的C＃，Java，而不是那些精确度低得多的人类语言，并且具有所有的假设和含糊之处。大多数具有常识的人都会知道细节有多少是足够的细节，但优秀的开发人员不是“大多数人”。这就是为什么我们最终得到像 \\这样的评论来添加一个b并将其存储在c 中（好吧，这太极端但你明白了。）
要求他们做一些他们讨厌做的事情并且坦率地说并不擅长（即使你确信这是正确的事情）只是一场已经失败的战斗。
我对你并不嗤之以鼻，但你应该将问题改为你如何说服其他开发者团队合作？
说真的，有些人认为你可以读懂他们的想法。
如果您是敏捷团队的一员，代码是集体拥有的，那么当您看到未注释，笨拙或难以阅读的代码时，请继续并更改（重构）它以便您理解它。如果有人抱怨，请告诉他们为什么并提前做好准备。你发现它不可理解，没有人拥有代码。
我们的策略是进行系统的代码审查，并拒绝未正确记录的代码（通过评论，正确的功能命名和组织等）。如果评论者不清楚，你会回到工作台上。
我会说“昨天我必须阅读你的一些代码。我能够理解它，但是不到或等于5条精心挑选的评论解释如何完成它的目标将允许我在大约十分之一的时间内阅读它然后我可能会担心理解一个而不是问题。我不是傻瓜，你也不聪明，因为你可以写出难以理解的东西。相反，如果你不能生成可读的文档+代码集合，那么你就不再是开发人员了。“
我很久以前就把这个钻进了我的脑海里：如果你写了一些东西而且有合理能力的人无法理解，那就是你的错，而不是他或她的错。这适用于用自然语言书写，它适用于用编程语言编写。
关于评论也有过类似的讨论。以下是评论代码时人们遵循的规则：你的“硬性规则”是什么？关于评论您的代码？。一些答案也有很好的理由说明为什么要对代码进行评论。
在你的评论欲望中显示智慧，他们更有可能倾听。
少即是多。
强调质量而非数量。
在我的团队中，推动对某些API中的所有内容发表评论。一些开发人员开始使用一种工具，通过查看方法名称和签名自动生成注释。
例如：
/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{
}
你能想到更大的屏幕空间浪费吗？您是否可以想到更多的脑循环浪费而不是阅读没有提供新信息的评论？
如果方法签名很明显，请不要说出来！如果我能在几秒钟内搞清楚，请不要将其放在评论中。正如其他人所说，告诉我为什么你选择这样做，而不是你做了什么。编写代码，使其显而易见。
以身作则。当他们看到正确的东西时，开发人员很容易受到影响，所以看到可靠的实践行动可能会鼓励他们做同样的事情。此外，您可以鼓励您的小组采用代码指标来解决代码可维护性和注释问题。例如，代码分析将为没有摘要文档的方法生成错误。
我目前工作的当前编码标准是评论每个功能。像这样的空白规则是有害的，永远不应该到位。有些情况（其中一些是常见的）添加注释会消除可读性。
class User {
getUserName() { /* code here */ }
}
将函数头添加到上面的代码中有什么意义？还有什么可以说besdies“获取用户名”。并非所有代码都需要注释。我的经验法则是：如果您没有添加函数签名没有的任何有用信息，请跳过注释。
评论应该是彻底的，写在意图层面（为什么不是如何），并且很少见。
编写代码时，我倾向于合理地评论。然后，我回过头来尝试删除尽可能多的注释，而不会降低代码的可理解性。 ＆gt; 80％的时间这就像提取一个命名良好的方法一样简单，这通常会导致注释只复制代码本身的信息。除此之外，如果有一段代码“需要”，那么评论我想方设法简化它或使其更清晰。
代码应该是自我记录的，并且使用正确的技术可以很容易地获得95％的方式。一般来说，如果我签到的代码中仍有任何注释，我认为这是一个失败。
取决于你拥有多少力量......
我发现一种非常有效的方法是将其作为基于同行的代码审查的固定部分 - 评论要点。如果有人评论说代码被严重评论，我会让开发人员对它表示满意，这基本上意味着他们必须通过打印并阅读它来描述足够的代码以便我理解它。我也会这样做。
值得注意的是，这对开发人员来说很受欢迎，尽管它听起来像是狄更斯。发生了两件事。首先，人们开始评论他们的代码。其次，严重评论的代码成了开发人员不太了解他们所写内容的标志（否则他们就会对其进行描述）。
唯一真正的缺点是，当修改错误修复等时，评论必须与代码保持同步。这几乎不可能在真正的开发商店中执行，但是一旦足够好的做法被刻上了它排序自然而然地发生了。
BTW我更喜欢代码本身的评论而不是Dostoevsky小说作为文档字符串。前者对后续程序员有用。后者只是一段很长的过时文本，填补了文档并误导了所有人。
让他们使用不熟悉的API，但是在非Internet连接的计算机上进行编程（如果您现在可以找到它们），这样他们就无法访问API文档。这实际上是他们在试图使用非文档的代码时强迫其他开发人员做的事情！
你还必须区分两种不同的意见：
API意见 (如果是的话，为什么不试或其他类似的文件):你可以问他们 使用他们自己的代码，在限制方案 (边界的条件，如空物体或空串或...)并看看他们是否实际管理记住怎么他们自己的职能在这些情况下
(这就是为什么我对 如果是的话，为什么不试，包括限值)内部评论 (内的源代码):你可以问问他们解释任何的功能，他们有的编码，只挑选一个函数 真的 高圈复杂程度, 和看到他们斗争的所有不同的代码的工作流程和决策支;)
嗯，总是有“如果你不评论你的代码，我们会找到其他人评论他们的代码”。方法。
更温和，告诉他们如果他们不记录和评论他们正在做什么，他们会非常放弃团队。代码不属于个人，除非他们是完全孤独的狼。它属于团队，团队，无论是公司还是社区。
“编写代码” =“以特殊语言编写命令序列” +“写评论”
在编写代码时对进行评论将是不言而喻的！ 你有没有评论已经3或4个月大的代码？ （当然，你有，但其他一切都很有趣！）
如果您的项目已经有详细记录，那么添加新代码的程序员可能会以类似的方式撰写评论。
@James Curran我100％同意！我可以阅读你的代码并找出你告诉编译器要做的事情;但这并不意味着你打算让编译器这样做。我知道我不是一个足够程度的程序员，相信每次我编写代码都会让我完全按照我的努力去做。另外，我经常发现，在我编写代码并试图解释我打算为代码做什么之后，我会在代码中发现愚蠢的逻辑错误。
一个想法是指出每个班级写一个或两个句子不到一分钟，每个方法写一个句子不到半分钟。
告诉他们使用Javadoc通知记录他们的函数和接口，然后通过Doxygen运行代码，为他们的代码生成看起来很酷的HTML文档。凉爽因素有时可能是一个很好的动力。
我使用了一种微妙的技巧：
我将项目中的警告级别设置为报告为错误。 我们的持续集成服务器正在构建整个解决方案以及每个ckeck-in上的XML文档。
如果开发人员不写评论，则构建失败！ 之后，他们必须写评论，所以过了一会儿，他们就习惯了。
在压力方面并不积极，但我发现这是纠正行为的好方法。
如果开发人员必须参与代码审查并接受良好的评论，他们应该能够获得线索。如果他们认为这种做法没有用，那么他们应该从他们的同行评审员那里得到一些反馈。
如果失败（假设您是主管/经理），那就将其作为绩效评估的一部分。如果你可以测量它，你可以根据它进行评估。
确保这是你评分的评论，因为被动攻击性开发者会将每一句话都记录为一个不那么微妙的FU。
我已成为我称之为
Headrick's Rule 的坚定信徒，以我的同事的名字命名，他发现激励某人做某事的好方法是让他们感到痛苦< em>不去做。在你的情况下，要求你的非评论开发人员花一两个小时来解释他们的代码，或许是为了“缓慢”。观众，也许在他们的午餐时间“避免项目滑点”会走很长的路。聪明的人 - 即使是顽固的人 - 快速学习！
在我看来（我在这里谈论.Net编程）如果你必须发表评论，你就无法使代码可读。答案通常是重构！
但是，如果您觉得必须发表评论，那么它应该始终是“为什么”。评论的类型，而不是解释代码的作用的评论。
在实际编码之前写下一个方法/类将会做什么有助于很多事情做好 - 而且你已经对它进行了评论。
只雇用优秀的工程师，确保他们的代码隐含地表明意图（使用评论和其他方式）。任何想要工作的人都必须做得对。苛刻，但公平，恕我直言。
