No comments. Now what?
Tags: comments
Published: 2023-10-12 22:57:41

---
title: No comments. Now what?
published: true
description: If we do not comment our code, that information should go somewhere else! Here are some places to send it to.
tags: comments
cover_image: https://upload.wikimedia.org/wikipedia/commons/thumb/e/e8/Mona_Lisa_margin_scribble.jpg/1920px-Mona_Lisa_margin_scribble.jpg
---

![A margin note, discovered in the University Library of Heidelberg, which proved that Lisa del Giocondo was the subject of Mona Lisa. Source: https://w.wiki/7czB](https://i0.wp.com/suspensao.blog.br/disbelief/wp-content/uploads/2023/10/1920px-Mona_Lisa_margin_scribble.jpg?fit=1200%2C360&ssl=1)

Traditionally, it is considered good practice to comment code. However, this wisdom has been revisited in recent times. At [Liferay](https://liferay.com), 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](https://blog.codinghorror.com/coding-without-comments/) on [this](https://www.youtube.com/watch?v=2a_ytyt9sf8) 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](https://github.com/liferay/liferay-portal/blob/c80c42d75b23ca8ec30153f94c88263dd468f889~/modules/apps/forms-and-workflow/calendar/calendar-test/src/testIntegration/java/com/liferay/calendar/util/test/CalendarUtilTest.java#L117-L121):

```java
Assert.assertNotNull(recurrence);
Assert.assertNull(recurrence.getUntilJCalendar());
Assert.assertEquals(0, recurrence.getCount());
```

These lines check if an event's [RRule](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html) has certain properties: it must exist, have a null "*until*" [`Calendar`](https://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html), 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](https://github.com/liferay/liferay-portal/commit/c80c42d75b23ca8ec30153f94c88263dd468f889) already clarified everything by moving these lines to a method and invoking it:

```java
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:

```java
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](https://github.com/liferay/liferay-portal/commit/3c431cbdc4eabb0eb7581b27c8eeae622ca768b0):

```java
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](https://github.com/liferay/liferay-portal/blob/043118eadf7c90c5d0182a6f7b5812472ebc142c/modules/dxp/apps/forms-and-workflow/portal-workflow/portal-workflow-kaleo-designer-web/src/main/resources/META-INF/resources/designer/kaleo_definition_version_action.jsp#L29-L34):

```jsp
<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](https://github.com/liferay/liferay-portal/commit/043118eadf7c90c5d0182a6f7b5812472ebc142c). 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](https://liferay.atlassian.net/browse/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](https://en.wikipedia.org/wiki/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](https://jupyter.org/) and [Quarto](https://quarto.org/).

Even more relevant, tools like [Javadoc](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html), [JSDoc](https://jsdoc.app/), [Doxygen](https://www.doxygen.nl/), 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](https://suspensao.blog.br/descrenca/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 text was originally posted in "*[*No comments. Now what?*](https://suspensao.blog.br/disbelief/no-comments-now-what/)*" at my blog* [*Suspension of Disbelief*](https://suspensao.blog.br/disbelief/no-comments-now-what/)*.)*