Comments and documentation syntax in Kotlin - Mini Project: Build & Apply

Comments and Documentation Syntax in Kotlin

📖 Scenario: You are writing a simple Kotlin program to keep track of a book's title and author. To make your code clear for others and yourself, you will add comments and documentation.

🎯 Goal: Learn how to write single-line comments, multi-line comments, and documentation comments in Kotlin.

📋 What You'll Learn

Create variables with exact names and values

Add a single-line comment explaining a variable

Add a multi-line comment explaining a block of code

Add a documentation comment for a function

Print the book details

💡 Why This Matters

🌍 Real World

Comments and documentation help programmers understand code quickly and maintain it easily, especially in team projects or when returning to code after some time.

💼 Career

Clear comments and documentation are essential skills for software developers to communicate their code's purpose and usage effectively.

1

Create variables for book title and author

Create two variables called bookTitle and bookAuthor. Set bookTitle to "The Kotlin Guide" and bookAuthor to "Jane Doe".

Kotlin

# Your code here

Hint

Use val to create variables with the exact names and values.

2

Add a single-line comment for the book title

Add a single-line comment above the bookTitle variable that says // This is the title of the book.

Kotlin

// Your comment here
val bookTitle = "The Kotlin Guide"
val bookAuthor = "Jane Doe"

Hint

Use // to write a single-line comment exactly as shown.

3

Add a multi-line comment explaining the variables

Add a multi-line comment above both variables that says exactly: /* This section defines the book details including title and author */

Kotlin

/*
Your multi-line comment here
*/
// This is the title of the book
val bookTitle = "The Kotlin Guide"
val bookAuthor = "Jane Doe"

Hint

Use /* and */ to write a multi-line comment exactly as shown.

4

Add a documentation comment for a function and print book details

Create a function called printBookDetails with no parameters. Add a documentation comment above it that says exactly: /** * Prints the book title and author */. Inside the function, print bookTitle and bookAuthor on separate lines using println. Then call printBookDetails().

Kotlin

/*
This section defines the book details
including title and author
*/
// This is the title of the book
val bookTitle = "The Kotlin Guide"
val bookAuthor = "Jane Doe"

// Your function and call here

Hint

Use /** */ for documentation comments and println to print each variable.

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