Comments and documentation syntax in Kotlin

Introduction

Comments help explain your code so others (and you) can understand it later. Documentation comments create helpful guides for your code.

To explain why a piece of code does something special.

To leave notes for yourself about what to fix or improve later.

To describe what a function or class does for other programmers.

To temporarily disable a line of code without deleting it.

To generate automatic documentation from your code.

Syntax

Kotlin

// This is a single-line comment
/* This is a
   multi-line comment */
/**
 * This is a documentation comment.
 * It is used to describe classes, functions, or properties.
 */

Single-line comments start with // and go to the end of the line.

Multi-line comments start with /* and end with */. They can span many lines.

Examples

This comment explains the next line of code.

Kotlin

// This is a single-line comment
val x = 5

This comment spans two lines and explains the code below.

Kotlin

/* This is a
   multi-line comment */
val y = 10

This is a documentation comment describing the add function. It helps generate documentation automatically.

Kotlin

/**
 * Adds two numbers and returns the result.
 * @param a first number
 * @param b second number
 * @return sum of a and b
 */
fun add(a: Int, b: Int): Int {
    return a + b
}

Sample Program

This program uses comments to explain what the code does. The documentation comment describes the add function, and single-line comments explain lines inside the code.

Kotlin

// This program adds two numbers

/**
 * Adds two integers and returns the sum.
 *
 * @param a first integer
 * @param b second integer
 * @return sum of a and b
 */
fun add(a: Int, b: Int): Int {
    // Return the sum
    return a + b
}

fun main() {
    val result = add(3, 4) // Call add function
    println("The sum is: $result")
}

Important Notes

Use comments to make your code easier to understand, but avoid obvious comments that just repeat the code.

Documentation comments start with /** and are used by tools to create API docs.

Keep comments up to date when you change your code to avoid confusion.

Summary

Comments explain your code and help others understand it.

Use // for single-line and /* ... */ for multi-line comments.

Documentation comments /** ... */ describe code elements and help generate docs.

Practice

1. Which of the following is the correct way to write a single-line comment in Kotlin?

easy

A. /* This is a single-line comment */

B.

C. // This is a single-line comment

D. # This is a single-line comment

Solution

1. Step 1: Identify single-line comment syntax in Kotlin

   Kotlin uses // to start a single-line comment.

2. Step 2: Compare options

   // This is a single-line comment uses //, which is correct. /* This is a single-line comment */ is for multi-line comments. <!-- This is a single-line comment --> is HTML style. # This is a single-line comment is used in some scripting languages but not Kotlin.

3. Final Answer:

   // This is a single-line comment -> Option C

4. Quick Check:

   Single-line comment = // [OK]

Hint: Single-line comments start with // in Kotlin [OK]

Common Mistakes:

• Using /* */ for single-line comments
• Using # or which are not Kotlin comments
• Confusing multi-line and single-line comment syntax

2. Which of the following is the correct syntax for a multi-line comment in Kotlin?

easy

A. /* This is a multi-line comment */

B.

C. /** This is a multi-line comment */

D. // This is a multi-line comment

Solution

1. Step 1: Recall multi-line comment syntax in Kotlin

   Kotlin uses /* ... */ to write multi-line comments.

2. Step 2: Analyze options

   /* This is a multi-line comment */ correctly uses /* ... */. // This is a multi-line comment is single-line comment syntax. /** This is a multi-line comment */ is documentation comment syntax. <!-- This is a multi-line comment --> is HTML comment syntax.

3. Final Answer:

   /* This is a multi-line comment */ -> Option A

4. Quick Check:

   Multi-line comment = /* ... */ [OK]

Hint: Multi-line comments use /* and */ to start and end [OK]

Common Mistakes:

• Using // for multi-line comments
• Confusing documentation comments /** */ with regular multi-line comments
• Using HTML style comments

3. What will be the output of the following Kotlin code?

fun main() {
    // println("Hello")
    println("World")
}

medium

A. Hello
World

B. World

C. Hello

D. No output

Solution

1. Step 1: Understand comment effect on code execution

   The line // println("Hello") is a comment, so it does not run.

2. Step 2: Identify which println runs

   Only println("World") runs, so output is "World".

3. Final Answer:

   World -> Option B

4. Quick Check:

   Commented code does not run = World [OK]

Hint: Commented lines do not execute, only uncommented print runs [OK]

Common Mistakes:

• Thinking commented println runs
• Expecting both lines to print
• Confusing comment syntax and output

4. Identify the error in the following Kotlin code snippet:

fun main() {
    /* This is a comment
    println("Hello")
}

medium

A. No error, code runs fine

B. Incorrect single-line comment syntax

C. Missing quotation marks in println

D. Missing closing */ for multi-line comment

Solution

1. Step 1: Check multi-line comment syntax

   The comment starts with /* but does not have a closing */.

2. Step 2: Understand impact of missing closing comment

   Without closing */, the compiler treats the rest as comment, causing syntax error.

3. Final Answer:

   Missing closing */ for multi-line comment -> Option D

4. Quick Check:

   Multi-line comments must close with */ [OK]

Hint: Always close multi-line comments with */ [OK]

Common Mistakes:

• Forgetting to close multi-line comments
• Confusing single-line and multi-line comment syntax
• Assuming code inside unclosed comment runs

5. Which comment style should you use in Kotlin to write documentation that tools can extract to generate API docs?

hard

A. /** This is a documentation comment */

B. /* This is a documentation comment */

C. // This is a documentation comment

D.

Solution

1. Step 1: Identify documentation comment syntax in Kotlin

   Kotlin uses /** ... */ for documentation comments that tools can parse.

2. Step 2: Compare with other comment types

   // This is a documentation comment is single-line comment syntax. /* This is a documentation comment */ is regular multi-line comment syntax. <!-- This is a documentation comment --> is HTML comment syntax.

3. Final Answer:

   /** This is a documentation comment */ -> Option A

4. Quick Check:

   Documentation comments use /** ... */ [OK]

Hint: Use /** ... */ for documentation comments in Kotlin [OK]

Common Mistakes:

• Using // or /* */ for documentation comments
• Confusing documentation comments with regular comments
• Using HTML comment style by mistake