Kotlin Comments

Types of Comments

// This is a comment
val name = "Kotlin"

/* This comment
   spans multiple
   lines */

/**
 * This function adds two numbers
 * @param a first number
 * @param b second number
 * @return sum of a and b
 */

// println("Debug info")
val result = calculate()

🔹 Single-line Comments

Use // for single-line comments:

fun main() {
    // This is a single-line comment
    println("Hello, World!")
    
    val age = 25  // Variable to store age
    
    // Calculate next year's age
    val nextAge = age + 1
    println("Next year you'll be $nextAge")
    
    // TODO: Add input validation
    // FIXME: Handle negative ages
}

🔹 Multi-line Comments

Use /* */ for multi-line comments:

/*
 * This is a multi-line comment
 * It can span multiple lines
 * Useful for longer explanations
 */
fun calculateArea(radius: Double): Double {
    /*
     * Formula for circle area:
     * Area = π × r²
     * Where π (pi) ≈ 3.14159
     */
    val pi = 3.14159
    return pi * radius * radius
}

fun main() {
    /* 
       Testing the calculateArea function
       with different radius values
    */
    val area1 = calculateArea(5.0)
    val area2 = calculateArea(10.0)
    
    println("Area of circle with radius 5: $area1")
    println("Area of circle with radius 10: $area2")
}

🔹 KDoc Documentation Comments

Use /** */ for documentation comments:

/**
 * Represents a simple calculator for basic arithmetic operations.
 * 
 * This class provides methods for addition, subtraction, multiplication,
 * and division of two numbers.
 * 
 * @author Kotlin Developer
 * @since 1.0
 */
class Calculator {
    
    /**
     * Adds two numbers together.
     * 
     * @param a the first number
     * @param b the second number
     * @return the sum of a and b
     * @throws IllegalArgumentException if inputs are invalid
     */
    fun add(a: Double, b: Double): Double {
        return a + b
    }
    
    /**
     * Divides the first number by the second number.
     * 
     * @param dividend the number to be divided
     * @param divisor the number to divide by
     * @return the result of division
     * @throws ArithmeticException if divisor is zero
     */
    fun divide(dividend: Double, divisor: Double): Double {
        if (divisor == 0.0) {
            throw ArithmeticException("Cannot divide by zero")
        }
        return dividend / divisor
    }
}

fun main() {
    val calc = Calculator()
    println("5 + 3 = ${calc.add(5.0, 3.0)}")
    println("10 / 2 = ${calc.divide(10.0, 2.0)}")
}

🔹 Nested Comments

Kotlin supports nested multi-line comments:

fun main() {
    /*
     * This is the outer comment
     * 
     * /* This is a nested comment
     *    It can contain other comments
     *    // Even single-line comments work here
     * */
     * 
     * Back to the outer comment
     */
    
    val message = "Nested comments work!"
    println(message)
    
    /*
     * Useful for commenting out large blocks
     * that already contain comments
     * 
     * /* Original comment:
     *    This function was supposed to do something
     * */
     * 
     * fun disabledFunction() {
     *     // This entire function is commented out
     *     println("This won't run")
     * }
     */
}

🔹 Best Practices for Comments

🔸 Examples of Good vs Bad Comments

// ❌ Bad: States the obvious
val age = 25  // Set age to 25

// ✅ Good: Explains the business logic
val age = 25  // Minimum age requirement for account creation

// ❌ Bad: Redundant
fun calculateTax(income: Double): Double {
    // Calculate tax by multiplying income by 0.2
    return income * 0.2
}

// ✅ Good: Explains the tax rate source
fun calculateTax(income: Double): Double {
    // Using 2024 standard tax rate for single filers
    return income * 0.2
}

// ✅ Good: Explains complex logic
fun isValidEmail(email: String): Boolean {
    // Simple email validation - checks for @ symbol and domain
    // More comprehensive validation should be added for production
    return email.contains("@") && email.contains(".")
}