第一阶段意见评论_评论意见

最新推荐文章于 2024-10-14 09:08:48 发布

danpu0978

最新推荐文章于 2024-10-14 09:08:48 发布

阅读量129

点赞数

原文链接：https://www.javacodegeeks.com/2015/08/thoughts-on-comments.html

版权

第一阶段意见评论

哇，告诉人们对他们的他妈的代码发表评论真是令人不安。这些React涵盖了从“ 刚刚阅读Clean Code，花花公子 ”到“ 也许有些评论但只有一点 ”到“ OMG是 ”的整个范围。

既然我已经冷静下来，我将以更少的精力再次解决该主题。我打算写一些关于高质量评论的观点，但是上周的讨论浮出了很多有趣的观点和事实，我想先介绍一下。

总览

以下是您和我对评论的一些想法。但是这篇文章不能涵盖有关该主题的所有发言。请随时指出您认为重要的其他因素！

评论与…

…文档

itch子，拜托！您不知道注释和文档之间的他妈的区别，对此您大声疾呼！！

月亮

事实证明，对于API文档（例如Javadoc或.NET的XML文档）是否也是注释，我们缺乏共识。在过去的一周中，这破坏了几次有趣的对话，而现在我必须假定，这是对该主题进行任何讨论时的重大误解的源头。

我坚信，是的，API文档只是注释，尽管格式特殊。这得到Wikipedia（请参阅有关注释或文档生成器的文章）， Javadoc和.NET的XML文档的文档（它们都称为文档注释 ）以及StackOverflow和Programmers StackExchange上相关问题的最高评价的支持。

此外，我认为所有评论都是一种文档形式，即使它只是针对其他开发人员，包括将来的我。当然，文档不仅可以包含注释。测试，示例应用程序，图表，自述文件，Wiki文章等都可以用来记录系统。

但是，不管我对这些术语的解释如何，对我来说显而易见的是，关于该主题的任何有意义的讨论都必须从交换我们发表评论时的意思开始。

当我说评论时 ，除非特别说明，否则包括存在于源文件中的所有形式的文档。

…清洁代码

我将采用这样的代码，即开发人员不使用全部名为“ ufw”，“ q”，“ q1”，“ ql”，“ qi”等的变量，甚至不使用完整的Javadoc（以其他因素为代价），任何一天。

各种腌菜

我完全同意泡菜。如果是干净代码或增值注释，我也希望使用干净代码。但是为什么会是或者呢？

这分解成一种经常表达的观点：将时间花在清理代码上总比写注释好。在评论可以增加价值的假设下（即使只是很少也只有一点），这种说法显然是错误的。随着改进代码的成本越来越高，在某些时候添加注释必须更加有效。

对于解释为什么按原样编写一段代码的注释尤其如此。干净的代码几乎无法提供此类上下文。

总的来说，我认为“没有注释的好代码”与“有注释的坏代码”是错误的二分法。干净的代码和良好的注释是对系统的补充。那么，为什么不花时间使代码尽可能简洁，然后在可以为将来的读者提供帮助的地方添加注释呢？

在软件世界中，有一种普遍的观念，即好的代码不需要注释，它是独立存在的。或那个注释是代码的味道。 […]

支持这一观点的人指出，注释很容易与代码不同步，并决定由于此方法不够完善，因此应完全避免。

这是一个错误的二分法，可以通过向队友明确说明代码和注释都需要检查来轻松避免。

Cedric Beust –您的代码并不代表自己

评论模式

无论是在本篇文章中还是在本篇文章中，我都从未说过我希望如何注释代码。我实际上还不确定，但是在讨论API之后，我将提出一个非常初步的建议。

蜜蜂

尽管Javadocs对于公共API很有用，但它们却是不适合公共消费的代码的反感。

罗伯特·马丁（Robert C. Martin）–清洁法规

我认为预选赛的公众充其量是模棱两可的，而最坏的情况是误导性的。我们应该寻找其他特征来识别值得记录的API。

什么是公开的？

可能的社会解释是“公众”，“公司外部的所有人”，“部门外部的所有人”等等。更多的技术解释是“每个人都从另一个系统调用此代码”和“每个人都从另一个模块调用此代码”。

在极端情况下，这使开发人员可以声称，由于公司之外的任何人都不会调用他们的代码，因此无需编写任何注释。

更常见的是，公众被理解为“来自大会外部的呼吁”（例如，来自另一个JAR的呼吁）。但是随后，无论是经常使用的代码是驻留在另一个程序集中还是驻留在另一个程序集中，这突然变得有所不同。这也没有多大意义。

重要的是什么？

API是可重用代码的缩影。流行的公共API可能被成千上万的开发人员使用。它通过以一种易于解决的方式抽象出一个实质性问题而变得流行。一个很好的促成因素是有用的文档，这些文档中的合同评论是不可或缺的一部分。

回到我们编写的微不足道的小API，包括反腐败层，实用程序方法集，手工UI控件，或我们希望在整个代码库中使用的任何其他代码。虽然很可能不太成功，但适用类似的规则。它们解决了具体的问题领域，并提供了供他人使用的抽象，如果用户能够找到解决方法，他们将可以更轻松地完成工作。

因此，与其衡量API的公开程度，不如考虑它会如何渗透我们的代码库。使用的次数越多，应记录的越好。

这是一组简单的规则，我认为这是与我的团队一起开发评论架构的起点：

简要解释API注释中类或接口的中央抽象。假设并不是每个开发人员都像您那样了解业务逻辑。
如果代码创建了应该在整个系统中使用的抽象，请为公众提供完整的Javadoc。花时间使评论有意义。
不要使用内联注释来解释代码的作用，除非使用了一些不可解开的不可避免的语言机制，这些机制无法提取到正确命名的类/方法/函数中。
请使用内联注释来解释非显而易见的设计决策（例如，已知错误或复杂的业务规则的变通办法）背后的原理。
如果更改代码，请在同一文件中查找可能需要更新的注释

当然，所有这些当然都在干净的代码，适当的测试之上，…现在，将其撕裂！ :)

由Farhad Sadykov在CC-BY 2.0下发布。

社会动力

通常，开发人员以团队形式工作。团队由人组成。人类容易受到压力。截止日期给人类带来了压力。办公室政治。个人问题。人们************** 注释可能非常有用，但是如果您依靠它们，它们将*会*过时。代码审查可以缓解这种情况，但是错误仍然会漏掉。

而且有些人不在乎。我几乎可以感觉到您明显的React即将到来：“这些人应该被Swift开除！”

对。再一次，让我们不要忘记办公室政治。开发团队包括老板的近亲侄子并不少见。

杰森·托马斯

考虑社会动态至关重要！团队必须自己决定哪种评论架构适合其需求，然后共同努力实现这一目标。结对编程或代码审查之类的开发技术将在很大程度上支持这一点。

Catch-22评论质量

您必须教给开发人员“好的”注释是什么，然后他们才能看到编写注释的价值。 “ //遍历数组并过滤出所有不良内容”与“ //删除每个语法上不正确的记录

”等等…

麦克风

是的，不断阅读格式错误或构思不当的评论并不会激发编写或维护高质量评论的动机。要说服人们采用新技术，就必须证明其好处。

话虽这么说，那些声称评论的人通常已经过时了，而且毫无用处的人通常也是由于不更新现有评论而造成问题的人。因此，一支重视评论并希望从中受益的团队必须防止这种自我实现的预言。

倾向与技巧

许多开发人员不喜欢甚至不喜欢写评论。此外，编写有意义的文档至少需要一些中等水平的书面技能，但并非所有开发人员都能达到。（这使他们声称注释不能添加代码中不清楚的内容。）当然，这两个方面会相互放大。

但是，至少可以说，基于是否愿意发表评论的决定是不专业的。克服它！如果有充分的理由反对评论，那就太好了，否则，请成为专业人士，然后再做。

此外，写作是一种比许多其他与开发有关的领域更容易达到足够水平的技能。另外，改进它通常对我们的生活有益，这对于我们学会成为优秀开发人员的大多数事情而言，都是不言而喻的。

可以接受的程序员和优秀的程序员之间的区别不是他们知道多少种编程语言，也不是他们是否喜欢Python或Java。这是他们是否可以传达自己的想法。通过说服他人，他们获得了影响力。通过编写清晰的注释和技术规范，他们可以让其他程序员理解他们的代码，这意味着其他程序员可以使用和使用他们的代码，而不必重写它们。缺少这个，他们的代码就一文不值。

Joel Spolsky –给计算机科学专业大学生的建议

杂项贡献

有几个较长的线程。其中一个由GMNightmare发起，包含了一个很好的例子，其中的评论节省了很多时间，而关于如何防止这种情况的疯狂讨论也有两次。我在很大程度上同意GMN的看法，在这种情况下，除了内联注释之外，其他所有事情都变得更加复杂。 Lukas Eder提出了另一个这样的例子。我们还讨论了Guava的一段代码。

肖恩·赖利（ Sean Reilly）提供了很棒的技术建议：