Why Comments and documentation syntax in Kotlin? - Purpose & Use Cases

The Big Idea

What if your future self could instantly understand your code without confusion or frustration?

The Scenario

Imagine you wrote a long Kotlin program last year. Now you want to fix a bug or add a feature, but you don't remember what each part does. You open the code and see only lines of confusing text with no hints or explanations.

The Problem

Without comments or documentation, understanding code is like reading a book in a foreign language. It takes a lot of time, causes mistakes, and makes teamwork frustrating because others can't easily follow your logic.

The Solution

Using comments and documentation syntax lets you add clear notes inside your Kotlin code. These notes explain what the code does, why it's there, and how to use it, making your code easy to understand for yourself and others.

Before vs After

✗ Before

fun calculate(x: Int, y: Int): Int {
    return x * y + 42
}

✓ After

/**
 * Calculates a special value by multiplying x and y,
 * then adding 42 as a constant offset.
 */
fun calculate(x: Int, y: Int): Int {
    // Multiply x and y
    return x * y + 42
}

What It Enables

Clear comments and documentation make your code a friendly guidebook that anyone can follow, improving teamwork and saving time.

Real Life Example

A team working on a Kotlin app uses documentation comments to explain each function's purpose. When a new member joins, they quickly understand the code without asking many questions.

Key Takeaways

Comments explain code inside the program.

Documentation syntax creates helpful guides for functions and classes.

They make code easier to read, maintain, and share.

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