📝 Ghi chú và KDoc

🎯 Mục tiêu: Hiểu cách viết ghi chú để giải thích code và sử dụng KDoc để tạo documentation chuyên nghiệp.

💡 Khái niệm

Comments (ghi chú) là phần văn bản trong code mà compiler bỏ qua. Chúng giúp:

Giải thích logic phức tạp
Ghi chú TODO cho công việc sau
Tạo documentation tự động

Kotlin hỗ trợ 3 loại comments:

Loại	Cú pháp	Mục đích
Single-line	`// ...`	Ghi chú ngắn
Multi-line	`/* ... */`	Ghi chú dài
KDoc	`/** ... */`	Documentation

📝 Single-line Comments

Dùng // cho ghi chú một dòng:

fun main() {
    // Khai báo biến lưu trữ tên người dùng
    val userName = "Bumbii"

    val age = 25  // Tuổi của người dùng

    println("Xin chào, $userName!")  // In ra lời chào
}

📝 Multi-line Comments

Dùng /* ... */ cho ghi chú nhiều dòng:

/*
 * Chương trình tính toán BMI
 * Tác giả: Bumbii Academy
 * Phiên bản: 1.0
 */
fun main() {
    val weight = 70.0
    val height = 1.75

    /*
       Công thức BMI:
       BMI = cân nặng (kg) / chiều cao² (m)
    */
    val bmi = weight / (height * height)

    println("BMI của bạn: $bmi")
}

Nested Comments (Comments lồng nhau)

Kotlin cho phép lồng comments - điều mà Java không hỗ trợ:

/*
 * Đây là comment ngoài
 * /* Đây là comment lồng bên trong */
 * Vẫn trong comment ngoài
 */

📚 KDoc - Documentation Comments

KDoc là hệ thống documentation của Kotlin, tương tự Javadoc. Sử dụng /** ... */:

/**
 * Tính tổng hai số nguyên.
 *
 * @param a Số nguyên thứ nhất
 * @param b Số nguyên thứ hai
 * @return Tổng của a và b
 */
fun sum(a: Int, b: Int): Int {
    return a + b
}

Các tag phổ biến trong KDoc

Tag	Mô tả	Ví dụ
`@param`	Mô tả tham số	`@param name Tên người dùng`
`@return`	Mô tả giá trị trả về	`@return Kết quả tính toán`
`@throws`	Exception có thể xảy ra	`@throws IOException Khi file không tồn tại`
`@see`	Tham chiếu đến element khác	`@see [OtherClass]`
`@since`	Phiên bản bắt đầu có	`@since 1.0`
`@sample`	Ví dụ sử dụng	`@sample samples.example`
`@property`	Mô tả property của class	`@property name Tên người dùng`

🔍 KDoc nâng cao

Document một Class

/**
 * Đại diện cho một người dùng trong hệ thống.
 *
 * Class này chứa thông tin cơ bản của người dùng bao gồm
 * họ tên và tuổi. Có thể sử dụng để hiển thị thông tin
 * hoặc xác thực tuổi.
 *
 * @property name Họ và tên đầy đủ của người dùng
 * @property age Tuổi của người dùng (phải >= 0)
 * @constructor Tạo một User mới với tên và tuổi
 *
 * @sample
 * ```
 * val user = User("Bumbii", 25)
 * println(user.isAdult()) // true
 * ```
 */
class User(val name: String, val age: Int) {

    /**
     * Kiểm tra xem người dùng đã đủ 18 tuổi chưa.
     *
     * @return `true` nếu tuổi >= 18, ngược lại `false`
     */
    fun isAdult(): Boolean = age >= 18
}

Markdown trong KDoc

KDoc hỗ trợ Markdown formatting:

/**
 * Xử lý chuỗi JSON.
 *
 * ## Tính năng
 * - Parse JSON string thành object
 * - Validate format
 * - Handle errors gracefully
 *
 * ## Ví dụ
 * ```kotlin
 * val result = parseJson("""{"name": "Bumbii"}""")
 * ```
 *
 * **Lưu ý:** Hàm này có thể throw exception nếu JSON không hợp lệ.
 *
 * @param jsonString Chuỗi JSON cần parse
 * @return Object đã được parse
 * @throws JsonParseException Khi chuỗi không phải JSON hợp lệ
 */
fun parseJson(jsonString: String): Any {
    // Implementation
}

Linking trong KDoc

Sử dụng [...] để link đến class/function khác:

/**
 * Tạo một [User] mới từ dữ liệu JSON.
 *
 * Sử dụng [parseJson] để xử lý chuỗi đầu vào.
 *
 * @see User
 * @see parseJson
 */
fun createUserFromJson(json: String): User {
    // Implementation
}

⚠️ Lưu ý quan trọng

Đừng comment những gì code đã nói rõ:

// ❌ BAD - Thừa thãi
val age = 25  // Gán 25 cho biến age

// ✅ GOOD - Giải thích WHY, không phải WHAT
val age = 25  // Tuổi tối thiểu để đăng ký tài khoản

🛠️ Thực hành

Bài tập: Viết KDoc cho class Calculator

/**
 * TODO: Thêm KDoc cho class này
 */
class Calculator {

    /**
     * TODO: Thêm KDoc cho hàm này
     */
    fun add(a: Double, b: Double): Double = a + b

    /**
     * TODO: Thêm KDoc cho hàm này
     */
    fun divide(a: Double, b: Double): Double {
        if (b == 0.0) throw ArithmeticException("Không thể chia cho 0")
        return a / b
    }
}

Lời giải:

/**
 * Máy tính đơn giản hỗ trợ các phép toán cơ bản.
 *
 * Cung cấp các phép toán: cộng, trừ, nhân, chia.
 *
 * @sample
 * ```
 * val calc = Calculator()
 * println(calc.add(10.0, 5.0))     // 15.0
 * println(calc.divide(10.0, 2.0))  // 5.0
 * ```
 */
class Calculator {

    /**
     * Cộng hai số thực.
     *
     * @param a Số hạng thứ nhất
     * @param b Số hạng thứ hai
     * @return Tổng của [a] và [b]
     */
    fun add(a: Double, b: Double): Double = a + b

    /**
     * Chia hai số thực.
     *
     * @param a Số bị chia
     * @param b Số chia (phải khác 0)
     * @return Kết quả của [a] / [b]
     * @throws ArithmeticException Khi [b] bằng 0
     */
    fun divide(a: Double, b: Double): Double {
        if (b == 0.0) throw ArithmeticException("Không thể chia cho 0")
        return a / b
    }
}

📱 Trong Android

Khi phát triển Android, KDoc giúp tạo documentation cho các component:

/**
 * Fragment hiển thị danh sách sản phẩm.
 *
 * Sử dụng RecyclerView để hiển thị danh sách.
 * Hỗ trợ pull-to-refresh và infinite scroll.
 *
 * @see ProductAdapter
 * @see ProductViewModel
 */
class ProductListFragment : Fragment() {

    /**
     * Làm mới danh sách sản phẩm từ server.
     *
     * Hiển thị loading indicator trong khi fetch data.
     * Nếu có lỗi, hiển thị error message.
     */
    fun refreshProducts() {
        // Implementation
    }
}

TODO và FIXME

IDE (IntelliJ IDEA / Android Studio) nhận diện các comment đặc biệt:

// TODO: Thêm validation cho input
fun processInput(input: String) {
    // FIXME: Bug - không xử lý Unicode đúng cách
    val processed = input.trim()
}

Bạn có thể xem danh sách TODO trong View → Tool Windows → TODO.

✅ Checklist - Tự kiểm tra

Sau bài học này, bạn có thể:

Sử dụng // cho single-line comments
Sử dụng /* */ cho multi-line comments
Viết KDoc cơ bản với @param, @return, @throws
Sử dụng Markdown formatting trong KDoc
Link đến class/function khác với cú pháp [ClassName]
Sử dụng TODO và FIXME comments

Tiếp theo: Biến trong Kotlin: val và var

Th.S Trần Huy Phúc

Kỹ sư phần mềm @Adnovum & Bumbii Academy