评论分类数据集_评论分类

评论分类数据集

注释可以用来传达代码的作用&＃xff0c;应该做什么&＃xff0c;不应该做什么&＃xff0c;为什么存在&＃xff0c;何时以及如何以及不应该使用它等等。

让我们对它们进行分类&＃xff01;

这不是很无聊吗&＃xff1f; 好吧&＃xff0c;尽管卡尔不这么认为。 我认为这是我们在讨论评论时的重要下一步&＃xff1a;

• 评论您的他妈的代码&＃xff01;
• 评论意见
• 分类学
• 成本与收益
• 未完待续 …

总览

将根据内容&＃xff0c;维护含义&＃xff0c;位置和替代方案对不同类型的注释进行比较。

这些图标来自HevnGrafix创建的“ 新闻和杂志”图标集 。

分类目录

叙述

有一些注释说明了代码的作用。 诸如“遍历客户列表”或“通过新产品的价格增加总数”之类的事情。

保养

对于这些意见在所有增加任何价值&＃xff0c;他们必须完全跟上时代的。 代码和注释之间的每次转移都将Swift导致混乱&＃xff0c;并很快将其忽略。

位置

这些通常是嵌入式注释。

保持它们半途可维护的唯一方法是只允许它们在以下几行中引用代码。 其他一切很快崩溃&＃xff0c;因为没有机制可以找到引用即将更改的代码的遥远注释。

备择方案

通过编写简洁的代码&＃xff0c;几乎可以使叙事变得多余。 仔细的命名&＃xff0c;透明的设计&＃xff0c;使用知名的模式等&＃xff0c;可以更好地解释代码&＃xff0c;并使其更易于维护。

人们普遍同意应避免这些评论。 仅在极少数情况下&＃xff0c;如果使用不可思议但不可避免的语言机制&＃xff0c;才有必要使用它们。

合约

然后是合同定义注释。 它们描述了代码单元的中央抽象&＃xff0c;代码单元如何与其依赖关系进行交互以及哪些前置条件和后置条件成立。

他们还谈到了代码做什么 &＃xff0c;但不像叙述的意见&＃xff0c;他们在声明样式这样做。 理想情况下&＃xff0c;可以读取它们而不是代码和测试。

保养

撰写和维护要兑现这一承诺的评论&＃xff0c;需要坚定的决心&＃xff0c;对细节的关注以及明确的语言。

成功执行此操作将大大增加注释的代码的可用性。 另一方面&＃xff0c;不清楚或完全错误的注释&＃xff0c;或者未能使合同和代码保持同步将导致很多混乱。

与旁白不同&＃xff0c;合同注释仅描述抽象行为&＃xff0c;而不是实现细节&＃xff0c;因此维护工作不那么紧张。

位置

在具有这些语言的任何语言中&＃xff0c;都应使用文档注释&＃xff08;例如Javadoc或.NET XML注释 &＃xff09;来表示此类别。

地方性势在必行。 合同注释最好只讨论单个概念&＃xff0c;并且在绝对不可避免的情况下&＃xff0c;仅提及其他代码单元&＃xff08;例如&＃xff0c;另一种方法&＃xff09;。 如果可能&＃xff0c;这仅以自动更新的链接的形式发生&＃xff08;例如Javadoc中的&＃64;see &＃xff09;。 否则&＃xff0c;评论应避免重复信息并创建单一事实来源。

备择方案

干净的代码和测试通常被认为是合同注释的替代方法。

测试的显着优势在于&＃xff0c;只要它们通过测试&＃xff0c;就可以保证设备显示出测试的行为。 当然&＃xff0c;由于措辞含糊和维护不善&＃xff0c;行为和文档可能会有所不同&＃xff0c;因此注释也不是一样。

仅在代码和测试中进行记录的缺点是&＃xff0c;从下至上建立高级理解需要上下文切换&＃xff0c;并且需要时间-可能很多。 如果随后不使用分析的代码&＃xff0c;很多新获得的知识可能很快就会被遗忘。

我认为比较干净的代码和测试是一个方面&＃xff0c;而合同的另一侧则是本次讨论中最关键的方面。 我在这里不再赘述&＃xff0c;而是重复我之前说过的话&＃xff1a;为什么不同时投资两者&＃xff1f;

技术背景

注释可以提供技术背景和澄清单位代码是有什么 。 他们可以解释何时可以使用它&＃xff0c;什么时候不可以使用&＃xff0c;一个人可以解决什么问题&＃xff0c;甚至可以举例说明如何使用它。

请注意&＃xff0c;其中一些信息也可能是合同的一部分&＃xff0c;但重要的是不要混淆这两个类别&＃xff01; 合同评论做出了承诺&＃xff0c;上下文评论解释了为什么这样做以及它的好处。

上下文注释对于学习该部分代码的任何人都将具有极大的价值&＃xff0c;无论是使用它还是对其进行修改。

保养

为了提供有用的上下文&＃xff0c;作者必须从读者的角度看待事物。 如果日常盲目罢工&＃xff0c;并且所有抽象和困难部分都非常明显&＃xff0c;那么这将是困难的。

与合同不同&＃xff0c;上下文注释并不是要取代对代码本身的阅读和理解&＃xff0c;而只是支持。 因此&＃xff0c;尽管它们应该是最新的&＃xff0c;但是可以忍受与代码的一些偏差。

位置

防止合同和上下文注释混淆很重要&＃xff01; 因此&＃xff0c;最好不要混合它们&＃xff0c;或者&＃xff0c;如果语言没有提供其他常用的机制&＃xff0c;则至少要清楚地将它们分开。

在Java中&＃xff0c;通常将它们组合为非Javadoc块&＃xff0c;通常在所描述的代码单元的开头。 从Java 8 开始 &＃xff0c;也可以使用新标签&＃64;apiNote和&＃64;implNote 。

就其本质而言&＃xff0c;此类注释可能不那么本地化&＃xff0c;并且暗指其他代码单元。 当然&＃xff0c;最好让他们留在本地并为他们找到有意义的地方。 但是&＃xff0c;这并不是必须的&＃xff0c;因为它们不一定总是最新的。

备择方案

读者通常可以找到生产代码来调用正在调查的单元&＃xff0c;或者查看其测试。 从这些调用站点获得更广泛的了解类似于从测试中了解合同&＃xff1a;它始终是最新的&＃xff0c;但可能是一种乏味的自下而上的方法。 另外&＃xff0c;这可能混合了预期和有问题的用例&＃xff0c;而没有进一步的区分或解释。

演示是描述一段代码的好方法。 但是&＃xff0c;它们很少见&＃xff0c;也必须加以维护。

历史背景

通常&＃xff0c;代码是根据某些要求非显而易见的设计规范或情况编写的。 也许可以采用一种更清洁的方法&＃xff0c;除非它没有一些非常具体的细节&＃xff0c;否则这些细节就无法纳入。 解释此类情况的文档提供了有价值的信息&＃xff0c;可帮助您理解为什么存在该代码。

记录历史上下文的一种形式是代码注释。

保养

他们应该总是一粒盐&＃xff0c;并以防止与其他评论混淆的形式写成。 理想情况下&＃xff0c;历史语境注释中应包含诸如“写作时”之类的短语&＃xff0c;以强调其短暂性。 如果他们清楚地陈述了自己的假设&＃xff0c;则更容易将它们标识为过时的。

我几乎没有理由花费时间来更新它们。 最好让它们即使稍稍老化也要站立&＃xff0c;并在它们描述的情况变化太大以至于无法使用时将其删除。

位置

这些注释甚至可能比提供技术上下文的注释更经常地描述或引用没有自然单数位置的概念。 如果同意不更新它们&＃xff0c;这是可以容忍的。

备择方案

这些信息也可以以提交消息的形式添加到源代码管理中。 这样做的好处是提交消息始终是“最新的”&＃xff0c;因为变更集本身是不可变的。 一条消息还可以涵盖不同文件之间的一组更改&＃xff0c;这通常很方便。 同时&＃xff0c;这可能是一个缺点&＃xff0c;因为必须在几个较大的消息中搜索非常本地的信息。 最后&＃xff0c;查找提交消息会增加从代码到文档的间接级别。

历史背景的另一个来源是与提交相关的问题。 它们可能包含许多难以在注释或提交消息中呈现的有价值的信息&＃xff0c;例如图表&＃xff0c;与客户的讨论&＃xff0c;到其他来源&＃xff08;如Wiki&＃xff09;的链接等。 但是问题甚至会从代码中进一步消除&＃xff0c;并且通常涵盖更高层次的领域。

由GlynLowe在CC-BY 2.0下发布 –我改变了视野和色彩。

反射

我们将评论分为以下四类&＃xff1a;

我希望这种分类法可以帮助团队确定是否以及如何使用评论。 我们可以看到不同种类具有不同的属性&＃xff0c;因此应单独讨论。

翻译自: https://www.javacodegeeks.com/2015/10/a-taxonomy-of-comments-2.html

评论分类数据集