评论分类

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

让我们对它们进行分类！

这不是很无聊吗？ 好吧，也许，尽管卡尔不这么认为。 我认为这是我们在讨论评论时的重要下一步：

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

总览

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

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

分类目录

叙述

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

保养

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

位置

这些通常是嵌入式注释。

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

备择方案

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

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

合约

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

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

保养

撰写和维护要兑现这一诺言的评论，需要坚定决心，注重细节，并且语言要明确。

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

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

位置

在具有这些语言的任何语言中，都应使用文档注释（例如Javadoc或.NET XML注释 ）来表示此类别。

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

备择方案

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

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

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

我认为比较干净的代码和测试是一个方面，而合同的另一侧则是此讨论中最关键的方面。 我在这里不做进一步介绍，而是重复我之前说过的话：为什么不投资两者？

技术背景

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

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

上下文注释对于学习该部分代码的任何人都是非常有价值的-无论是使用它还是对其进行修改。

保养

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

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

位置

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

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

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

备择方案

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

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

历史背景

通常根据要求非显而易见的设计的某些规范或情况来编写代码。 也许如果没有一些非常具体的细节，否则可能会采用更清洁的方法，否则这些细节将无法纳入。 文档解释这样的情况下提供了有价值的信息，了解为什么代码存在。

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

保养

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

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

位置

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

备择方案

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

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

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

反射

我们将评论分为以下四类：

	内容	保养	位置	备择方案
		目标	成本	形成	地区性
叙述	什么 （描述性）	比赛 展示	很高	排队	非常 重要	干净的代码
合约	什么 （说明性）	比赛 行为	高	doc。 注释	重要	干净的代码， 测试
技术 语境	做什么的	是 有帮助的	介质	块 注释	可取的	干净的代码， 测试，演示
历史的 语境	为什么	如果删除 过时的	非常低	指出 暂时性	可取的	提交味精， 问题

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

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