代码欢迎得注释代码_甚至良好的代码注释也会恶化

代码欢迎得注释代码

正如我在之前的博客文章中提到的那样 ，我最近一直在与Infinispan合作 。 我喜欢Infinispan和PostgreSQL文档的一件事是，每个产品的文档都非常清楚该文档适用于该产品的哪个版本，并且它们每个都使查找其他版本或当前版本的文档变得容易。 例如， PostgreSQL 9.5文档在顶部列出了“其他版本的此页面”，并提供指向相同文档其他版本的链接。 Infinispan 8.1文档就是一个Infinispan示例，它不仅在URL中包含版本，而且还以非常明显的方式指出：“这是专门为Infinispan 8.1编写的。” 对于Infinispan文档，版本化的文档可以帮助我意识到某些类级别的Javadoc文档不再正确。

org.infinispan.manager.DefaultCacheManager类的基于Javadoc的类级别描述提供了我希望看到的核心API类文档的类型。 它解释了通常需要的类实例的类型和数量，甚至提供了基于代码的类的“样本用法”。 不幸的是，此描述比以前 （但现在不再）实现CacheManager接口的当前类DefaultCacheManager更适用于旧接口CacheManager 。 以下屏幕快照显示了DefaultCacheManager的8.2 Javadoc文档。

至少从Infinispan 4 （由于具有JBoss Cache的特性 ，开始使用Infinispan的第一个版本）以来，此CacheManager Javadoc文档似乎已存在于org.infinispan.manager.CacheManager接口上。 那时的org.infinispan.manager.DefaultCacheManager类实现了CacheManager并且具有与实现的接口几乎相同的Javadoc文档，如下面的屏幕快照所示。

Infinispan 5引入了另一个CacheManager作为类（ org.infinispan.cdi.CacheManager ）。 Infinispan 6删除了CacheManager类，并在注释中弃用了CacheManager接口 ，“此接口仅用于与Infinispan 4.0向后兼容。最终，它将在以后的版本中删除。 如有需要，请使用EmbeddedCacheManager或CacheContainer 。” 在Infinispan 7.0 Javadoc中没有提到CacheManager （类或接口），但是DefaultCacheManager类仍然引用CacheManager就像它是一个接口。

这是一个很好的示例，说明随着API和其他文档结构的更改，即使良好的代码注释也会随着时间而恶化。 我已经在几个工作的代码库中看到了这种效果：即使是首次编写时准确而有用的代码内注释也可能会变得不那么有用，甚至在事情发生变化而代码内文档没有变化时也会产生误导作用。和他们一起改变。 当文档在多个结构中重复时，更可能发生这种情况，因此，当代码更改时，注释仅在一个位置而不是另一个位置被更新或删除。

我不想暗示我认为不应该编写Javadoc或其他注释或代码内文档，因为我绝对认为编写良好的代码内文档可能非常有用。 但是，也确实不应该一次写注释，而是希望在某些时候不需要更改注释。 编码中的文档需要与其所描述的代码一样谨慎。 否则，一次可以准确描述结构的代码内文档实际上可能最终会混淆对它预期将有助于描述的结构的理解。

翻译自: https://www.javacodegeeks.com/2016/09/even-good-code-comments-deteriorate.html

代码欢迎得注释代码