How I froze for 30 seconds as I didn’t know that block comments can get nested when converting code into Kotlin.

Hi! This is Ohashi, Android app engineer.

Lately, I’ve been converting some Java code into Kotlin, and I’d like to write about a moment that made me go “Huh?” while I was doing so.

Block comments written in Java turned out a bit strange after conversion.

Although the original Java code was working as usual, the converted Kotlin code was somehow all commented out!

Those familiar with Kotlin might already have an idea of what happened, well… turns out that it is now possible to nest block comments. With that in mind, I’ll briefly explain what was the issue.

Below code displays an useful comment left by the previous maintainer of this project. Please note that as I can’t share code from the original project I’m providing an equivalent code snippet. Also, I’m using 「…」for brevity, so please don’t think too much of it.

/**
* Below Kitkat(20) … /res/drawable/*.xml …can’t be specified
* This class uses…
*/
 class FilterableState {
 }

This comment indicates support for versions up to Android API 19.
Although it might appear as if the code was hidden using the [-] button in the IDE, the truth is that all code for the FilterableState class was commented out.
When I saw this at a glance, it was a mystery to me why it turned out like this.

After been stuck for about 30 seconds, I finally figured out that /*.xml ...can't be specified is where the nested comment was hiding.

…“Ah!, I see!”, What a nice game of “find the differences”. Even though nested comments can be very useful, it appears as if they can also lead to some puzzling situations, so just remember to be mindful when using them.

I did find a vague reference on nested block comments in Kotlin’s public documentation:

Unlike Java, block comments in Kotlin can be nested.

Swift also allows nested block comments

When I shared my experience with my colleagues, I received a comment from an iOS engineer letting me know that nesting comments is also an available feature in Swift. And sure enough, when I tried copy-pasting the same code into Swift I did get the same result.
This is also pointed out in Swift’s public documentation. I find this one to be a bit more detailed:

Nesting multiline comments is allowed, but the comment markers must be balanced.

It looks like there is trend to allow nesting block comments in relatively new languages.

Thinking on where to use nested comments

It appears to be ideal to use /* */ in the scenario where you want to comment out a particular selection of code containing many lines with the least difference possible. Unfortunately, Java does not allow nesting block comments, so all lines must be commented out using //, making all of them appear in the “diff”.
Kotlin on the other hand, allowing for nested block comments, makes it possible to comment out all those lines with a “diff” of only 2 lines.

For example, in the case we want to completely comment out both methods in the code below:

/**
* Test [arg] held by test method 1
*/
 fun firstMethod(arg: Object) {
 …
 }
/**
* Test [arg] held by test method 2
*/
 fun secondMethod(arg: Object) {
 …
 }

We can do so by following below example. The “diff” should only display the /*and */ lines.

/*
/**
* Test [arg] held by test method 1
*/
 fun firstMethod(arg: Object) {
 …
 }
/**
* Test [arg] held by test method 2
*/
 fun secondMethod(arg: Object) {
 …
 }
 */

Nested comment blocks might also prove helpful when writing code documentation. However, removing code instead of commenting it out is also a valid approach, so I’m not really sure how frequently I’ll be using them.

Wrapping it up

Comment block nesting is something that I accidentally stumbled upon while converting Java code into Kotlin. Experiences like this that help find new techniques are probably a bit rare, so I think I’ll use this opportunity to try and use nested block comments a bit more.

On another note, it appears as if younger programmers are not using “hogehoge” (Japan’s version of foobar) for their programming samples anymore. They may even ask “what is that supposed to mean?”…
After finding out about this when I googled “hogehoge”, I decided to rewrite my code sample.

It looks like there is a difficult road ahead for my old “hogehoge” self to work with this new features and techniques, but I’ll keep steadily walking through it!