Traditionally, it is considered good practice to comment code. However, this wisdom has been revisited in recent times. At Liferay, for example, we follow a policy of not commenting code. Personally, I am an enthusiast of this philosophy. But I don’t want to present or defend this strategy here, there is a lot of good material on this subject. I want to discuss an open question.
Whoever comments wants to convey some important information. What information is this? And, most importantly, where can we register it? Let’s look at some alternatives.
What do these lines do?
Function names are excellent for explaining what the code does. If a block of code requires a comment, consider extracting it into a function or class. The name of the entity will already clarify its purpose.
Observe, for example, the lines below, taken from this test class:
Assert.assertNotNull(recurrence);
Assert.assertNull(recurrence.getUntilJCalendar());
Assert.assertEquals(0, recurrence.getCount());These lines check if an event’s RRule has certain properties: it must exist, have a null “until” Calendar, and a count of zero.
The concepts are complex; even I would be confused rereading these asserts. A comment could explain them. But this commit already clarified everything by moving these lines to a method and invoking it:
assertRepeatsForever(recurrence);Those assertions were checking if the event repeats indefinitely! No comment was needed—fortunately, as these asserts were in various tests.
What is happening here?
If a comment would explain something relevant at runtime, consider turning it into a log message! Check the example below:
if (Validator.isBlank(serviceAccountKey)) {
// If no credentials are set for GCS Store, the library will
// use Application Default Credentials.
_googleCredentials =
ServiceAccountCredentials.getApplicationDefault();
}
else {
_googleCredentials = ServiceAccountCredentials.fromStream(
new ByteArrayInputStream(serviceAccountKey.getBytes()));
}This comment may be relevant to someone reading the code. However, it would be crucial for someone investigating an authentication issue. Therefore, in practice, I chose to log a message:
if (Validator.isBlank(serviceAccountKey)) {
if (_log.isInfoEnabled()) {
_log.info(
"No credentials set for GCS Store. Library will use " +
"Application Default Credentials.");
}
_googleCredentials =
ServiceAccountCredentials.getApplicationDefault();
}
else {
_googleCredentials = ServiceAccountCredentials.fromStream(
new ByteArrayInputStream(serviceAccountKey.getBytes()));
}Why are they here?
Comments to explain why certain lines are there are also common. A better place to share this information is in commit messages.
These days, for example, I was asked to help with some code I worked on years ago. Reading a JSP—remember, years ago—I found these lines:
<liferay-portlet:renderURL portletName="<%= KaleoDesignerPortletKeys.KALEO_DESIGNER %>" var="viewURL">
<portlet:param name="mvcPath" value="/designer/view_kaleo_definition_version.jsp" />
<portlet:param name="redirect" value="<%= currentURL %>" />
<portlet:param name="name" value="<%= kaleoDefinitionVersion.getName() %>" />
<portlet:param name="draftVersion" value="<%= kaleoDefinitionVersion.getVersion() %>" />
</liferay-portlet:renderURL>This tag is generating a URL to be used elsewhere. But my trained eyes found the portletName parameter strange. This value is usually set automatically.
A git blame clarified everything when I found this commit. The message is clear:
LPS-74977 / LPS-73731 By making the render URL explicitly use the Kaleo Designer name, it will be valid when rendered in another portlet.
I get it! This code will probably be invoked by some other portlet. In this case, the value would be automatically set by the other application, and for some reason, we want to avoid that.
(By the way, that’s why I prefer small commits: they make it easier to discover the reason for very specific code snippets. It’s like every line of code has a comment! It’s not a unanimous position, though: some prefer larger commits.)
The purpose of the line was clarified. But why can it be invoked by another application? This is not usual…
Why was this change made?
Well-written code explains how something was implemented. The commit message explains the why, but in a local context. How do you explain the broader motivation behind code without resorting to comments?
Issue tracker tickets are excellent for this. Typically written to guide development, these documents are very helpful in interpreting the code. If we add the ticket key to the commit message, we can track the reasons.
Returning to the example above. We found that a line allows using the same code in multiple portlets. But this is rarely necessary. Why do we need to reuse the code in this case? Fortunately, the message mentions two tickets. I checked the older one; I arrived at LPSA-64324:
[Information Architecture] EE — As a portal admin, I would like to access all workflow portlets from the control panel section under the same tab.
The title already helps, and the text clarifies it even more. For usability reasons, three different applications started appearing in tabs of the same portlet. It makes complete sense!
The comments we like
It’s important to highlight that we are trying to avoid disorganized comments that intertwine with the code and attempt to explain difficult-to-understand sections. There are various comments, often with standardized formats, that do not hinder readability. An obvious example is the copyright header.
Another effective way to use comments is through literate programming. In this programming style, comments take the spotlight: the source code contains more prose than executable code. This is useful when explaining the algorithm is more important than reading it, as in academic research and data analysis. Not surprisingly, it is the paradigm of popular tools like Jupyter Notebook and Quarto.
Even more relevant, tools like Javadoc, JSDoc, Doxygen, etc. read comments in a specific format to generate documentation. These comments do not affect readability. On the contrary, Javadocs are great for explaining how to use these entities. Combined with tools like my dear Doctest, we even get guarantees of accuracy and correctness!
A World of Possibilities
These are just a few examples of alternatives to comments. There are many other options, such as wikis and blogs. I’ve even found explanations for code I wrote myself on Stack Overflow! We can think of even more solutions to meet different needs. The key point is that with these tools at our disposal, adding comments directly to the code becomes unnecessary.
Naturally, not commenting is just one way to write readable code. Comments are not forbidden; in fact, there are strategies that can make them effective. However, in my experience, avoiding comments often leads to better results, and these techniques help document important information that doesn’t fit directly into the code.
Are you a follower of the “no comments” strategy? If so, where else do you convey information? If not, how do you ensure effective comments? What type of comment do you not see being replaced by these approaches? I’d love to hear your opinions.
(This post is a translation of “Sem Comentários. E Agora?” from my blog Suspensão de Descrença.)