Over a million developers have joined DZone.

Even Good Code Comments Deteriorate

DZone's Guide to

Even Good Code Comments Deteriorate

Comments and documentation stand to benefit as much from versioning as code does. Otherwise, we see them deteriorate much the same as legacy code. Do you agree?

· Java Zone ·
Free Resource

Java-based (JDBC) data connectivity to SaaS, NoSQL, and Big Data. Download Now.

As I mentioned in a previous blog post, I've been working a bit with Infinispan recently. One of the things that I like about Infinispan's and PostgreSQL's documentation is that each product's documentation makes it very clear which version of the product the documentation applies to and they each make it easy to find other or more current versions of the documentation. For example, the PostgreSQL 9.5 documentation lists "This page in other versions" across the top with links to other versions of the same documentation. An Infinispan example is the Infinispan 8.1 documentation that not only includes the version in the URL, but also states in very obvious fashion, "This is written specifically for Infinispan 8.1." In the case of the Infinispan documentation, the versioned documentation helped me realize when some class-level Javadoc documentation was no longer correct.

The Javadoc-based class level description for class org.infinispan.manager.DefaultCacheManager provides the type of core API class documentation that I like to see. It explains the types and number of instances of the class would commonly be expected and even provides a code-based "Sample usage" of the class. Unfortunately, this description applies more to the old interface CacheManager than the current class DefaultCacheManager that formerly (but no longer) implemented the CacheManager interface. The following screen snapshot shows the 8.2 Javadoc documentation for DefaultCacheManager.

Image title

This Javadoc documentation for CacheManager appears to have been on the interface org.infinispan.manager.CacheManager since at least Infinispan 4 (first version of Infinispan because of its JBoss Cache heritage). The class org.infinispan.manager.DefaultCacheManager at that time implemented CacheManager and had almost the same Javadoc documentation as the interface it implemented as shown in the next screen snapshot.

Image title

Infinispan 5 introduced another CacheManager as a class (org.infinispan.cdi.CacheManager). Infinispan 6 removed that CacheManager class and deprecated the CacheManager interface with comment, "This interface is only for backward compatibility with Infinispan 4.0.Final and it will be removed in a future version. Use EmbeddedCacheManager or CacheContainer wherever needed." There is no mention of a CacheManager (class or interface) in Infinispan 7.0 Javadoc, but the DefaultCacheManager class still references CacheManager like it's an interface.

This is an example of how even good code comments can deteriorate over time as APIs and other documented constructs change. I have seen this effect in several code bases that I've worked on: even in-code comments that are accurate and helpful when they are first written can become less helpful or even misleading when things change and the in-code documentation doesn't change with them. This is more likely to happen when the documentation is repeated across multiple constructs such that when the code changes, the comments only get updated or removed in one of the places and not the other.

I don't want to imply that I think Javadoc or other comments or in-code documentation should not be written because I definitely think that well-written in-code documentation can be highly useful. However, it's also true that comments are not something to be written once with the expectation that they won't need to be changed at some point. In-code documentation needs to be treated with the same care and attention as the code it describes. Otherwise, the in-code documentation that at one time accurately described a construct might actually end up confusing understanding of the construct it's expected to help describe.

Connect any Java based application to your SaaS data.  Over 100+ Java-based data source connectors.

comments ,documentation ,javadoc ,code

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}