Chú thích trong Java: một dòng, nhiều dòng và Javadoc

Chú thích dùng để làm gì

Chú thích (comment) là phần chữ trong mã nguồn mà trình biên dịch Java hoàn toàn bỏ qua. Nó không bao giờ trở thành một phần của chương trình khi chạy: nó chỉ tồn tại cho người đọc code. Bạn dùng chú thích để giải thích vì sao một việc được làm theo cách nào đó, để lại lời nhắc, hoặc để tạm tắt code mà không cần xóa.

Java có ba loại chú thích: một dòng (//), chú thích khối nhiều dòng (/* */) và chú thích tài liệu Javadoc (/** */). Tất cả đều làm cùng một việc cơ bản là bị bỏ qua khi biên dịch, nhưng mỗi loại dùng trong những tình huống khác nhau.

Chú thích một dòng

Hai dấu gạch chéo (//) bắt đầu một chú thích kéo dài đến cuối dòng hiện tại. Trình biên dịch bỏ qua mọi thứ từ // đến chỗ xuống dòng.

public class Main {
    public static void main(String[] args) {
        // Print a greeting to the console
        System.out.println("Hello, Java!");

        int score = 90; // a comment can also sit after code
        System.out.println(score);
    }
}

Để ý rằng chú thích thứ hai nằm chung dòng với code thật. Mọi thứ trước // vẫn chạy; chỉ phần sau nó bị bỏ qua. Đây là kiểu chú thích phổ biến nhất cho các ghi chú ngắn.

Chú thích khối nhiều dòng

Khi ghi chú kéo dài vài dòng, chú thích khối gọn hơn so với thêm // vào đầu từng dòng. Chú thích khối bắt đầu bằng /* và kết thúc bằng */. Mọi thứ nằm giữa hai dấu này, dù bao nhiêu dòng, đều bị bỏ qua.

public class Main {
    public static void main(String[] args) {
        /*
         * This program shows a block comment.
         * The leading asterisks on each line are just a
         * convention for readability - they are not required.
         */
        System.out.println("Block comments are handy.");
    }
}

Các ký tự * thẳng hàng dọc mép trái là một quy ước trình bày, không phải quy tắc. Chỉ có /* mở và */ đóng mới thực sự quan trọng.

Tắt code bằng chú thích

Chú thích là cách tiêu chuẩn để tắt code trong lúc thử nghiệm mà không cần xóa nó. Dùng // cho một dòng, hoặc chú thích khối để tắt nhiều dòng cùng lúc.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Chạy chương trình và bạn sẽ chỉ thấy hai dòng "runs" được in ra. Các lời gọi println đã bị biến thành chú thích thì vô hình với trình biên dịch.

Một cái bẫy thường gặp: chú thích khối không lồng nhau được. Dấu */ đầu tiên đóng chú thích, bất kể trước đó có bao nhiêu /*. Vì vậy bạn không thể bọc một khối /* ... */ bên trong một khối /* ... */ khác: dấu */ bên trong kết thúc toàn bộ chú thích và phần còn lại trở thành lỗi cú pháp. Nếu cần tắt một vùng code đã chứa chú thích khối, hãy dùng // trên từng dòng (hầu hết trình soạn thảo làm việc này chỉ bằng một phím tắt).

Chú thích tài liệu Javadoc

Chú thích Javadoc trông giống chú thích khối nhưng bắt đầu bằng /**, tức hai dấu sao. Nó dùng để mô tả một lớp, phương thức hoặc trường, và nằm ngay phía trên thứ nó mô tả. Công cụ javadoc biến các chú thích này thành tài liệu API dạng HTML có thể duyệt được, và IDE hiển thị chúng thành tooltip khi rê chuột.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

Các tag @param, @return và @throws là những trường có cấu trúc mà công cụ hiểu được. Với trình biên dịch, đây vẫn chỉ là một chú thích bị bỏ qua: giá trị của nó nằm hoàn toàn ở tài liệu được tạo ra và các gợi ý IDE dành cho lập trình viên khác (và cho chính bạn, sáu tháng sau).

Chú thích tốt và chú thích thừa

Một chú thích nên giải thích điều mà code không tự nói được. Chú thích chỉ nhắc lại code sẽ gây rối mắt và dễ lỗi thời khi code thay đổi.

// Bad: just repeats what the code obviously does
int i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Hãy cố làm cho code dễ đọc nhờ tên rõ ràng và cấu trúc tốt, và để dành chú thích cho câu hỏi vì sao: ý định, sự đánh đổi, trường hợp biên và liên kết đến ngữ cảnh. Nếu bạn thấy mình phải viết chú thích để giải thích một dòng khó hiểu, đó thường là dấu hiệu nên đổi tên biến hoặc tách ra một phương thức riêng.

Tiếp theo: biến

Giờ bạn đã biết cách chú thích code, khối xây dựng tiếp theo là lưu trữ dữ liệu. Trang tiếp theo nói về biến (variable): cách khai báo, các kiểu dữ liệu chúng chứa, và những quy tắc Java áp đặt vì nó là ngôn ngữ kiểu tĩnh.