Kotlin Comments - Types and How to Add a Comment

1. What are Kotlin Comments?

In the world of modern programming languages, Kotlin stands out for its conciseness and developer-friendly features. Like many other languages, Kotlin also enables developers to write comments within their code to improve readability and collaboration, and certainly, those comments are not compiled or interpreted in the final output. In this tutorial, we will discuss the importance of a comment in Kotlin, various types, and some best practices to know how comments contribute to the overall development process.

An example of a Kotlin comment is shown below.

/* Some Basic Information */
fun main () {
	println("My name is John Doe.")
	print("My age is : ") // Using print will not add a new line
	print(20)
}

My name is John Doe.
My age is : 20

2. Types of Comments in Kotlin

We can include a comment in Kotlin code in three different ways, just like CSS language comments. These three types of comments are described below.

2.1. Single-Line Kotlin Comment

We can add a single-line comment in Kotlin code using the //, and it terminates at the end of the line. We usually use single-line Kotlin comments for brief explanations or annotations. See the example below.

fun addNumbers(a: Int, b: Int): Int {
	return a + b
}
fun main () {
	println("sum of numbers = " + addNumbers(21,13))
}
// The addNumbers function is used to calculate the sum

2.2. Multi-Line Kotlin Comment

In Kotlin programming, we enclose a multi-line comment between /* and */. All the text or code between the two asterisks (*) will be considered a comment. We can also comment out the code blocks by using multi-line comments. Moreover, a multi-line comment can span from one to many lines.

/*
We defined the isEven() function.
It will return "true", if the number is even.
It will return "false", if the number is odd.
*/
fun isEven(number: Int): Boolean {
	return (number and 1) == 0
}
fun main() {
	var chk1 = isEven(11)
	var chk2 = isEven(14)
	println(chk1)
	println(chk2)
}

false
true

2.3. Documentation Comments KDoc

In Kotlin language, we can add (KDoc) comments, which are similar to PHP documentation comments. These documentation comments are a modification of multi-line comments and commence with /**. We usually define and explain our code functions, classes, and other code properties in a structured manner. These documentation comments are later extracted as project docs. Also, KDoc supports some extra components like @param, @return, etc. Check the following Kotlin code to comprehend the KDoc comments.

/**
* This function calculates the sum of all numbers between a given starting and ending number (inclusive).
*
* @param startNumber [Int] The first number in the range to be summed.
* @param endNumber [Int] The last number in the range to be summed.
* @return [Int] The sum of all numbers between `startNumber` and `endNumber`.
*/
fun calculateSum(startNumber: Int, endNumber: Int): Int {
	var sum = 0
	for (num in startNumber..endNumber) {
		sum += num
	}
	return sum
}
fun main() {
	val startNumber = 5
	val endNumber = 10
	val sum = calculateSum(startNumber, endNumber)
	println("The sum of numbers between $startNumber and $endNumber is: $sum")
}

3. Purpose of Comments in Kotlin

This section elaborates on the importance or purpose of a comment in Kotlin code, which seems to be a plus point like every programming language. Read the below headings to know the purpose of Kotlin's comments.

3.1. Documentation

Whenever we need to explain a segment of code, we include a comment before this segment, which will also be served for documentation purposes. In this, we can include an explanation of the code and its functionality. Further, this documentation comment will be helpful for other developers who come across this Kotlin code or collaborate with the project.

3.2. Clarification

Sometimes, the rationale and intent behind a chunk of code is not vivid immediately, the Kotlin developers add comments that would surely serve useful insights about that code block. As a result, the code will easily be understood along with the logic behind it.

3.3. TODOs and Reminders

Usually, developers leave reminders or mark TODOs by using Kotlin comments, and this practice is often useful. These reminders and TODOs would later allow the programmers to easily identify the areas and improve the code in future versions.

4. What are the Best Practices For Adding a Comment in Kotlin?

We have seen the method to add a comment, and also we have learned the features and importance of Kotlin comments. Let us find out the best practices for including comments in our code so that we get optimized results and more productivity.

4.1. Be Concise and Clear

Always keep your comments concise and to the point and clearly state the purpose or intention behind the code.

4.2. Update Comments

Whenever you make changes to your code, update your comments also, so that they remain clear and reflective of the current codebase.

4.3. Avoid Redundancy

Keep your focus on the code functionality provide useful insights, and stop adding redundant Kotlin comments i.e. repeating simply what the code is doing.

4.4. Descriptive Comments

Be sure to add descriptive comments where required and practice adding descriptive variables directly in your code. In this way, code will require less description.