Biểu tượng chim cắt của Kestrel Exams KESTREL EXAMSLUYỆN TẬP ĐỂ ĐẠT
Bản dịch này do AI thực hiện và chưa được người bản ngữ kiểm duyệt. Nếu có khác biệt, bản tiếng Anh là bản chính. Mã nguồn được giữ nguyên bằng tiếng Anh. Ứng dụng luyện tập và tài liệu cho các kỳ thi chứng chỉ của Hoa Kỳ chỉ có bằng tiếng Anh. Read in English
JavaĐọc trong 18 phútMã đã được kiểm chứng

Quy ước đặt tên và Javadoc: @param, @return và phần chú thích trở thành trang web

Các kiểu đặt tên của Java là những thói quen mà trình biên dịch không bao giờ kiểm tra, và chú thích Javadoc là các ghi chú mà một công cụ riêng biến thành trang web. Bài hướng dẫn này lấy một lớp thẻ khách hàng thân thiết của quán cà phê được đặt tên tệ rồi sửa từng bước cho đến khi nó đúng quy ước và được ghi chú đầy đủ. Mọi đoạn mã đều đã được biên dịch và chạy trên OpenJDK 21.

Luyện tập chủ đề này trong ứng dụng miễn phí →Tất cả bài hướng dẫn Java

Một thẻ tích tem với bố cục in sẵn#

Hãy hình dung một thẻ khách hàng thân thiết bằng giấy của quán cà phê. Tên quán được in lớn ở trên cùng, tên bạn viết trên một dòng, và chín ô chờ đóng tem. Con tem thứ chín được một ly miễn phí. Các quy định in chữ nhỏ ở mặt sau.

Không có luật nào bắt thẻ phải trông như vậy, nhưng quán nào cũng làm thế, nên thẻ nào cũng đọc được trong một giây. Java có hai điều tương tự:

  • Quy ước đặt tên là bố cục in sẵn. Một quy ước (convention) là thói quen mà mọi người tuân theo nhưng trình biên dịch không yêu cầu. Người đọc dựa vào đó để phân biệt một lớp, một biến và một hằng số.
  • Javadoc là phần chữ nhỏ: một loại chú thích đặc biệt giải thích cách dùng một lớp, được viết sao cho một công cụ có thể biến nó thành trang web.

Bài hướng dẫn này xây dựng một lớp, LoyaltyCard. Nó bắt đầu với tên tệ và không có chú thích; mỗi phần sửa một điều.

Hãy thử trước

Đây là bản nháp đầu tiên: một lớp viết chữ thường, một phương thức viết chữ hoa, các trường chỉ một chữ cái. Nó có biên dịch được không? Nếu có, nó in ra gì sau 20 con tem?

Xem đáp án

Nó biên dịch và chạy được: mọi tên đều xấu nhưng hợp lệ. 20 con tem với 9 tem một ly miễn phí là 20 / 9, bằng 2.

loyaltycard.java
public class loyaltycard {
    public static final int max = 9;
    private String N;
    private int s;

    public loyaltycard(String n) {
        N = n;
    }

    public void ADD() {
        s++;
    }

    public int Free() {
        return s / max;
    }

    public static void main(String[] args) {
        loyaltycard C = new loyaltycard("Rosa");
        for (int i = 0; i < 20; i++) {
            C.ADD();
        }
        System.out.println(C.N + ": " + C.s + " stamps, " + C.Free() + " free drinks");
    }
}
Rosa: 20 stamps, 2 free drinks

Tệp là loyaltycard.java vì một lớp public nằm trong tệp có đúng tên của nó. Nó chạy được, nhưng hãy đọc to các tên: ADD như đang hét, Free trông như một lớp, C.N chẳng nói lên điều gì.

Kiểm tra bẫy: chia số nguyên hay chia số thực?

s / max chia một int cho một int, nên Java bỏ phần dư: 20 / 9 là 2, không phải 2,22. Ở đây đó chính là điều ta muốn, vì không ai được 0,22 ly. Thu nhỏ về ranh giới: 8 con tem cho 0, và đúng 9 cho 1, giống như thẻ giấy.

Bốn kiểu đặt tên, và mỗi kiểu cho bạn biết điều gì#

Bạn vốn đã chọn một từ để đặt tên cho biến, như int total. Quy ước của Java thêm một điều: các chữ hoa cho biết tên đó thuộc loại nào.

KiểuTrông như thế nàoDùng choTrên thẻ
PascalCaseviết hoa mọi từlớpLoyaltyCard
camelCasetừ đầu viết thường, các từ sau viết hoabiến, trường, tham số, phương thứcownerName, addStamp
UPPER_SNAKE_CASEtoàn chữ hoa, dấu gạch dưới giữa các từhằng sốSTAMPS_PER_FREE_DRINK
chữ thườngtoàn chữ thường, các phần nối với nhau bằng dấu chấmgói (package)java.util

camelCase có các bướu ở giữa, như lạc đà; PascalCase viết hoa cả từ đầu. Một gói (package) là một nhóm lớp có tên. Một hằng số (constant) là một trường static final: final nghĩa là nó không bao giờ nhận giá trị mới, static nghĩa là lớp dùng chung một bản sao. Phương thức thường là động từ (addStamp), biến là danh từ (stamps), và i dùng cho biến đếm vòng lặp là ổn.

Hãy thử trước

Hãy đổi tên bản nháp trước khi xem đáp án. loyaltycard, max, N, s, ADD và Free nên trở thành gì?

Xem đáp án

LoyaltyCard, STAMPS_PER_FREE_DRINK, ownerName, stamps, addStamp, freeDrinksEarned. Các tên rõ nghĩa khác đúng kiểu cũng được: stampCount tốt không kém stamps.

Ở đây chỉ có tên thay đổi. Một tên chỉ là một nhãn, nên hãy dự đoán đầu ra giống nhau.

LoyaltyCard.java
public class LoyaltyCard {
    public static final int STAMPS_PER_FREE_DRINK = 9;
    private String ownerName;
    private int stamps;

    public LoyaltyCard(String name) {
        ownerName = name;
    }

    public void addStamp() {
        stamps++;
    }

    public int freeDrinksEarned() {
        return stamps / STAMPS_PER_FREE_DRINK;
    }

    public static void main(String[] args) {
        LoyaltyCard card = new LoyaltyCard("Rosa");
        for (int i = 0; i < 20; i++) {
            card.addStamp();
        }
        System.out.println(card.ownerName + ": " + card.stamps + " stamps, "
                + card.freeDrinksEarned() + " free drinks");
    }
}
Rosa: 20 stamps, 2 free drinks

Giống hệt, và giờ nó đọc như tiếng Anh: card.addStamp(), card.freeDrinksEarned().

Nếu bạn biết Python

Python viết free_drinks_earned với docstring nằm bên trong hàm; Java viết freeDrinksEarned với chú thích tài liệu nằm phía trên. Thói quen Python vẫn biên dịch được, nên hãy bỏ chúng một cách có chủ ý.

Điều trình biên dịch kiểm tra, và điều nó không kiểm tra#

Bản nháp đầu tiên đã chứng minh: trình biên dịch không bắt buộc quy ước đặt tên. Nó sẵn sàng chấp nhận một lớp tên x9_Q. Đồng đội của bạn thì không. Điều nó kiểm tra:

  • Tên hợp lệ. 2ndCard không hợp lệ, vì tên không thể bắt đầu bằng chữ số; second_card hợp lệ, chỉ là không đúng quy ước. Các quy tắc nằm trong định danh, từ khóa và literal.
  • Cùng một cách viết mỗi lần. Java phân biệt chữ hoa chữ thường, nên card.addstamp() lỗi với cannot find symbol, chính là lỗi bạn sẽ gặp với Scanner bên dưới. Đó cũng là lý do string với s thường bị lỗi (xem bài hướng dẫn viết lớp).
  • Tên tệp. Một lớp public phải nằm trong tệp có đúng tên của nó. Trình biên dịch kiểm tra rằng chúng khớp nhau, chứ không kiểm tra tên có bắt đầu bằng chữ hoa hay không.

Ba loại chú thích#

Bạn đã gặp hai dạng đầu trong cấu trúc của một chương trình Java. Dạng thứ ba trông gần giống dạng thứ hai, và đó là cái bẫy.

DạngViết làDùng cho
Chú thích dòng// đến hết dòngmột ghi chú nhanh bên cạnh một dòng
Chú thích khối/* … */, số dòng tùy ýmột ghi chú dài hơn cho người đọc mã nguồn
Chú thích Javadoc/** … */: dấu gạch chéo và hai dấu saotài liệu cho người dùng lớp

Với mọi thứ trong bài hướng dẫn này, trình biên dịch vứt bỏ cả ba loại. Chỉ có công cụ javadoc quan tâm. Đó là một chương trình thứ hai trong JDK, bộ công cụ đã cho bạn javac. Nó đọc chỉ những chú thích bắt đầu bằng /** và biến chúng thành trang web. Dấu * ở mỗi dòng giữa chỉ để cho gọn gàng; javadoc bỏ nó đi.

Đây là thẻ với mỗi loại một cái: Javadoc ở lớp và ở addStamp, một chú thích dòng ở stamps, và một chú thích khối một dấu sao ở freeDrinksEarned.

LoyaltyCard.java
/**
 * A coffee-shop loyalty card that collects one stamp per drink.
 *
 * @author Sam Rivera
 * @version 1.0
 */
public class LoyaltyCard {
    public static final int STAMPS_PER_FREE_DRINK = 9;
    private String ownerName;
    private int stamps;          // starts at 0, like every int field

    public LoyaltyCard(String name) {
        ownerName = name;
    }

    /**
     * Adds one stamp for a drink just bought.
     */
    public void addStamp() {
        stamps++;
    }

    /*
     * Returns how many free drinks the stamps have earned.
     */
    public int freeDrinksEarned() {
        return stamps / STAMPS_PER_FREE_DRINK;
    }

    public static void main(String[] args) {
        LoyaltyCard card = new LoyaltyCard("Rosa");
        for (int i = 0; i < 20; i++) {
            card.addStamp();
        }
        System.out.println(card.ownerName + ": " + card.stamps + " stamps, "
                + card.freeDrinksEarned() + " free drinks");
    }
}
Rosa: 20 stamps, 2 free drinks

Đầu ra giống nhau: trình biên dịch đã bỏ qua mọi chú thích. Giờ hãy chạy javadoc trên cùng tệp. Dòng $ là lệnh gõ trong terminal; -d docs nghĩa là “đặt các trang vào một thư mục tên docs”. Lần chạy thật này được rút gọn ở chỗ bạn thấy ....

Hãy thử trước

javadoc cảnh báo no comment cho mỗi phần public mà nó thấy chưa được ghi chú. Nó sẽ nêu tên những phần nào của thẻ này?

Xem đáp án

Bốn phần: hằng số, hàm tạo, freeDrinksEarned và main. Chú thích ở freeDrinksEarned mở đầu bằng /*, nên javadoc không tính nó.

$ javadoc -d docs LoyaltyCard.java
...
Generating docs/LoyaltyCard.html...
LoyaltyCard.java:8: warning: no comment
    public static final int STAMPS_PER_FREE_DRINK = 9;
                            ^
LoyaltyCard.java:12: warning: no comment
    public LoyaltyCard(String name) {
           ^
LoyaltyCard.java:26: warning: no comment
    public int freeDrinksEarned() {
               ^
LoyaltyCard.java:30: warning: no comment
    public static void main(String[] args) {
                       ^
...
4 warnings

Phần cuối cùng đó có một chú thích, nhưng nó mở đầu bằng /*, nên javadoc không bao giờ thấy nó.

Kiểm tra cái bẫy: một dấu sao hay hai?

Một chú thích mở đầu bằng /* là chú thích thông thường, kể cả khi nó chứa @return, và trình biên dịch sẽ không bao giờ cảnh báo bạn. Hãy kiểm tra mọi chú thích tài liệu đều mở đầu bằng dấu gạch chéo, dấu sao, dấu sao.

Chú thích Javadoc đặt ở đâu, và chú thích của lớp#

Một chú thích Javadoc ghi chú cho thứ được khai báo ngay bên dưới nó. Vị trí đó là mối liên kết duy nhất, nên không được có gì xen vào giữa.

Hãy thử trước

Hai chú thích Javadoc trong tệp này bị đặt sai chỗ. javadoc sẽ nói khai báo nào không có chú thích?

Xem đáp án

Lớp và getStamps. Chú thích của lớp nằm phía trên một dòng import, nên nó không ghi chú cho gì cả. Chú thích của phương thức nằm bên trong thân, dưới phần đầu, nên nó chỉ là một chú thích trong mã.

LoyaltyCard.java
/**
 * A coffee-shop loyalty card.
 */
import java.util.ArrayList;

public class LoyaltyCard {
    private int stamps;

    /** Creates an empty card. */
    public LoyaltyCard() {
    }

    public int getStamps() {
        /** Returns the number of stamps. */
        return stamps;
    }
}
$ javadoc -d docs LoyaltyCard.java
...
LoyaltyCard.java:6: warning: no comment
public class LoyaltyCard {
       ^
LoyaltyCard.java:13: warning: no comment
    public int getStamps() {
               ^
...
2 warnings

Vậy: các dòng import trước, rồi chú thích của lớp, rồi public class. Chú thích của phương thức đặt phía trên phần đầu phương thức, không bao giờ bên trong dấu ngoặc nhọn. (Một dòng như @Override được tính là một phần của phần đầu, nên Javadoc đặt phía trên nó.)

Hãy nhìn lại chú thích của lớp thẻ ở phần trước. Câu đầu tiên của nó là phần tóm tắt, được sao chép vào các bảng tóm tắt của javadoc. Sau đó là các thẻ khối (block tag), tức là những từ bắt đầu bằng @ ở đầu dòng. @author ghi tên người viết lớp (mỗi tác giả một dòng). @version là phiên bản của lớp của bạn, không phải của Java, thường kèm một ngày. javadoc không đưa cả hai lên trang trừ khi bạn thêm -author và -version.

Import, và vì sao thẻ không đọc bàn phím#

“Import trước” gợi ra một câu hỏi mà có thể bạn đã mang theo từ chương trình đầu tiên. Đây là bản nháp của chương trình sẽ điền thông tin vào các thẻ, đọc bàn phím bằng Scanner (xem bài hướng dẫn nhập từ bàn điều khiển).

Hãy thử trước

Bản nháp này dùng String, System và Scanner, không có dòng import nào. Trình biên dịch sẽ không tìm thấy cái nào?

Xem đáp án

Chỉ Scanner, được báo hai lần vì tên xuất hiện hai lần trên dòng đó.

CardCounter.java
public class CardCounter {
    public static void main(String[] args) {
        Scanner keyboard = new Scanner(System.in);
        System.out.print("Name on the card: ");
        String name = keyboard.nextLine();
        System.out.println("Welcome, " + name);
    }
}
CardCounter.java:3: error: cannot find symbol
        Scanner keyboard = new Scanner(System.in);
        ^
  symbol:   class Scanner
  location: class CardCounter
CardCounter.java:3: error: cannot find symbol
        Scanner keyboard = new Scanner(System.in);
                               ^
  symbol:   class Scanner
  location: class CardCounter
2 errors

String, System và Math nằm trong gói java.lang, mà Java tự động import vào mọi tệp. Đó là lý do bạn chưa bao giờ phải import chúng. Scanner nằm trong java.util, nên tệp cần import java.util.Scanner; ở đầu, hoặc dùng tên đầy đủ (fully qualified name) java.util.Scanner mỗi lần.

Vì sao không cho thẻ một trường Scanner riêng? Nó sẽ biên dịch được khi đã import, và vẫn là sai. Hãy tự hỏi: thẻ có còn hợp lý trong một ứng dụng không có bàn phím không? Tên và các con tem thuộc về thẻ; bàn phím thuộc về chương trình, và thẻ phải chạy được trong một ứng dụng điện thoại không có bàn điều khiển. Vì vậy phần nhập liệu ở lại cạnh main, nơi được chuyển ra một tệp riêng, CardCounter.java, và truyền các giá trị vào.

Chú thích phương thức: @param và @return#

Chú thích của một phương thức có cùng hình dạng, với hai thẻ khác. @param mô tả một tham số, tên chính xác đứng đầu: @param drinks how many free drinks to redeem. @return mô tả giá trị được trả về. Hãy để phần đầu phương thức quyết định: mỗi tham số một @param, và một @return trừ khi nó là void hoặc là hàm tạo.

Phần đầu (header)@param@return
public LoyaltyCard(String name)một, namekhông có: là hàm tạo
public void addStamp()không cókhông có: void
public int getStamps()không cómột
public boolean redeem(int drinks)một, drinksmột

Một setter void (phương thức thay đổi một trường) có @param và không có @return.

Hãy thử trước

Hãy viết Javadoc cho getter public int getStamps() (getter là phương thức chỉ trả về một trường).

Xem đáp án

Một câu tóm tắt và một @return, không có @param vì dấu ngoặc đơn trống:

/**
 * Returns how many stamps are on the card right now.
 *
 * @return the number of stamps, never negative
 */

Hãy thử trước

Bản nháp này có ba lỗi về thẻ. Hãy dùng bảng ở trên để tìm chúng trước khi đọc lần chạy javadoc.

Xem đáp án

@return ở hàm tạo, @return ở phương thức void addStamp, và một @param bắt đầu bằng phần mô tả thay vì tên drinks.

LoyaltyCard.java
/**
 * A coffee-shop loyalty card.
 */
public class LoyaltyCard {
    private int stamps;

    /**
     * Creates an empty card.
     *
     * @return a new card
     */
    public LoyaltyCard() {
    }

    /**
     * Adds one stamp.
     *
     * @return nothing
     */
    public void addStamp() {
        stamps++;
    }

    /**
     * Checks for enough stamps.
     *
     * @param how many drinks to check
     * @return true if there are enough stamps
     */
    public boolean canRedeem(int drinks) {
        return stamps >= drinks * 9;
    }
}
$ javac LoyaltyCard.java
$ javadoc -d docs LoyaltyCard.java
...
LoyaltyCard.java:10: error: invalid use of @return
     * @return a new card
       ^
LoyaltyCard.java:18: error: invalid use of @return
     * @return nothing
       ^
LoyaltyCard.java:27: error: @param name not found
     * @param how many drinks to check
              ^
LoyaltyCard.java:30: warning: no @param for drinks
    public boolean canRedeem(int drinks) {
                   ^
...
3 errors
2 warnings

javac không in gì, tức là nó biên dịch được: các thẻ nằm trong chú thích. javadoc báo ba lỗi và hai cảnh báo. Nó đọc how là tên tham số, không tìm thấy, và nhận ra drinks không có @param. Cảnh báo thứ hai, được rút gọn ở đây, lặp lại lỗi của hàm tạo bằng những từ dài hơn.

Giờ là thẻ hoàn chỉnh, với một getter và một phương thức redeem đổi tem lấy đồ uống. Bài hướng dẫn viết lớp giải thích vì sao các trường vẫn là private.

Kiểm tra cái bẫy: >= hay >?

redeem kiểm tra stamps >= needed. Hãy thu nhỏ về ranh giới: đúng 9 con tem, đổi 1 ly, cần 9. Với >, khách hàng đã kiếm được ly đó sẽ bị từ chối.

Vì vậy lần chạy dưới đây nhập một khách hàng có đúng 9 ly. Hãy dự đoán trước: 1 ly miễn phí, việc đổi thành công, còn lại 0 con tem. Chữ in đậm là thứ người dùng đã gõ.

Tệp LoyaltyCard.java chứa:

/**
 * A coffee-shop loyalty card that collects one stamp per drink.
 * <p>
 * Every <strong>9 stamps</strong> earn one free drink.
 *
 * @author Sam Rivera
 * @version 2.0, October 2026
 */
public class LoyaltyCard {
    /** Stamps needed for one free drink. */
    public static final int STAMPS_PER_FREE_DRINK = 9;

    private String ownerName;
    private int stamps;

    /**
     * Creates an empty card for a new customer.
     *
     * @param name the name to print on the card
     */
    public LoyaltyCard(String name) {
        ownerName = name;
    }

    /**
     * Returns how many stamps are on the card right now.
     *
     * @return the number of stamps, never negative
     */
    public int getStamps() {
        return stamps;
    }

    /**
     * Adds one stamp for a drink just bought.
     */
    public void addStamp() {
        stamps++;
    }

    /**
     * Returns how many free drinks the stamps have earned.
     *
     * @return the number of whole free drinks earned
     */
    public int freeDrinksEarned() {
        return stamps / STAMPS_PER_FREE_DRINK;
    }

    /**
     * Trades stamps for free drinks, if the card has enough.
     *
     * @param drinks how many free drinks to redeem
     * @return true if the drinks were redeemed, false if not
     */
    public boolean redeem(int drinks) {
        int needed = drinks * STAMPS_PER_FREE_DRINK;
        if (stamps >= needed) {
            stamps -= needed;
            return true;
        }
        return false;
    }

}
CardCounter.java
import java.util.Scanner;

public class CardCounter {
    public static void main(String[] args) {
        Scanner keyboard = new Scanner(System.in);
        System.out.print("Name on the card: ");
        String name = keyboard.nextLine();
        System.out.print("Drinks bought: ");
        int drinks = keyboard.nextInt();

        LoyaltyCard card = new LoyaltyCard(name);   // values are passed in
        for (int i = 0; i < drinks; i++) {
            card.addStamp();
        }
        System.out.println(name + " has earned " + card.freeDrinksEarned() + " free drink");
        System.out.println("Redeem 1: " + card.redeem(1));
        System.out.println("Stamps left: " + card.getStamps());
    }
}
Name on the card: Theo
Drinks bought: 9
Theo has earned 1 free drink
Redeem 1: true
Stamps left: 0

Cả ba đều khớp. Nếu việc đổi in ra false, dự đoán của bạn đã bắt được lỗi. Hãy làm như vậy khi một công cụ AI đưa mã cho bạn: quyết định xem nó nên in gì, rồi so sánh.

Hãy tự gõ đoạn này

Đừng dán. Hãy thêm stampsToNextFreeDrink(), trả về cần thêm bao nhiêu con tem cho ly miễn phí tiếp theo. Viết Javadoc trước, chọn các thẻ chỉ từ phần đầu phương thức. Kiểm tra 13 con tem và 0 con tem bằng tay.

Xem đáp án

Không có tham số, nên không có @param; nó trả về một int, nên một @return:

/**
 * Returns how many more stamps the card needs for its next free drink.
 *
 * @return a number from 1 to 9
 */
public int stampsToNextFreeDrink() {
    return STAMPS_PER_FREE_DRINK - stamps % STAMPS_PER_FREE_DRINK;
}

Toán tử % cho phần dư: 13 con tem còn dư 4, nên cần thêm 5; 0 dư 0, nên cần thêm 9.

HTML bên trong Javadoc, và trang web mà nó trở thành#

javadoc viết các trang web, được tạo từ HTML, ngôn ngữ thẻ mà trình duyệt đọc. Vì vậy các thẻ HTML thường dùng như <p> và <strong> được phép trong chú thích Javadoc và đi thẳng lên trang. javadoc có kiểm tra chúng: một thẻ cũ như <font> bị báo là lỗi. Chú thích của lớp thẻ dùng <p> để bắt đầu một đoạn (chỉ một dòng trống thì không) và <strong> để in đậm.

Mặt trái: với HTML, một dấu < trần bắt đầu một thẻ, nên viết stamps < 9 trong chú thích Javadoc khiến javadoc báo error: malformed HTML. Hãy viết &lt; thay vào, hoặc {@code stamps < 9}, in ra đúng như đã viết. Đây là lần chạy trên LoyaltyCard.java hoàn chỉnh với -author và -version. Bản ghi này đầy đủ.

$ javadoc -d docs -author -version LoyaltyCard.java
Loading source file LoyaltyCard.java...
Constructing Javadoc information...
Creating destination directory: "docs/"
Building index for all the packages and classes...
Standard Doclet version 21.0.12.1+1-1-24.04.4-Ubuntu
Building tree for all the packages and classes...
Generating docs/LoyaltyCard.html...
Generating docs/package-summary.html...
Generating docs/package-tree.html...
Generating docs/constant-values.html...
Generating docs/overview-tree.html...
Building index for all classes...
Generating docs/allclasses-index.html...
Generating docs/allpackages-index.html...
Generating docs/index-all.html...
Generating docs/search.html...
Generating docs/index.html...
Generating docs/help-doc.html...

Không cảnh báo, không lỗi. Dòng Standard Doclet version nêu tên JDK đã chạy javadoc, nên máy của bạn sẽ hiện phiên bản của bạn. (Doclet là phần của javadoc viết ra các trang.) Trên JDK 21, thư mục docs giờ chứa 31 tệp: 11 trang HTML (mỗi dòng Generating một trang) cộng với một tệp định dạng, các script, hình ảnh và tệp tìm kiếm. Các phiên bản JDK khác ghi ra một bộ hơi khác.

Mở docs/index.html trong trình duyệt và nhấp vào tên lớp. LoyaltyCard.html hiện phần tóm tắt, “9 stamps” in đậm, và các dòng Version: và Author:. Bên dưới là các bảng tóm tắt của hằng số, hàm tạo và các phương thức. Sau đó mỗi phương thức có một mục chi tiết, với Parameters: và Returns: được tạo từ các thẻ của bạn.

Các trường private bị thiếu: mặc định javadoc chỉ ghi tài liệu cho các phần public (và protected), dành cho người dùng lớp. Các trang chính thức của String và Scanner được tạo bằng chính công cụ này.

Điều mới trong bài hướng dẫn này#

  1. PascalCase, camelCase, UPPER_SNAKE_CASE và tên gói viết chữ thường.
  2. Trình biên dịch kiểm tra tên hợp lệ và nhất quán, không kiểm tra quy ước.
  3. /** */ là loại chú thích duy nhất javadoc đọc.
  4. Javadoc nằm ngay phía trên thứ nó ghi chú.
  5. @author và @version.
  6. java.lang là tự động; Scanner cần import và thuộc về chương trình.
  7. @param cho mỗi tham số, @return chỉ khi có giá trị trả về.
  8. HTML bên trong Javadoc.
Một câu để mang vào phòng thi

Quy ước đặt tên là thói quen dành cho con người, và Javadoc là một chú thích /** */ dành cho một công cụ: trình biên dịch không kiểm tra cái nào. Đặt mỗi Javadoc ngay phía trên thứ nó ghi chú, với một @param cho mỗi tham số và @return chỉ khi có giá trị trả về.

Những chỗ dễ sai#

  • Mở đầu một chú thích tài liệu bằng /*. Một dấu sao tạo ra chú thích thông thường mà javadoc bỏ qua. Hãy dùng /**.
  • @return ở phương thức void hoặc hàm tạo. Cả hai đều không trả về giá trị; javadoc báo invalid use of @return.
  • Phần mô tả đứng trước tên trong @param. Từ đầu tiên phải là tên tham số chính xác.
  • Javadoc đặt sai chỗ. Ngay phía trên phần đầu: không phải bên trong thân, không phải phía trên các import.
  • Quên import Scanner. java.util không tự động. (Import String không gây hại nhưng không bao giờ cần: java.lang là tự động.)
  • Một trường Scanner trong một lớp như LoyaltyCard. Hãy đọc đầu vào trong main; truyền giá trị vào.

Trong bài thi: Với câu hỏi “viết Javadoc”, điểm thường dành cho phần mở đầu /**, một câu tóm tắt, đúng tên các tham số, và không có @return ở void. Hãy đọc câu hỏi hai lần, trả lời, rồi đọc lại để kiểm tra bạn đã làm đủ mọi phần.

Luyện tập#

Hãy trả lời từng câu trên giấy trước khi xem lời giải. Mọi đáp án có chạy mã đều đã được kiểm tra bằng cách biên dịch và chạy mã đó.

  1. Đổi mọi tên để theo quy ước Java. Trình biên dịch đã bắt buộc những thay đổi nào của bạn?
    public class library_book {
        public static final int maxRenewals = 2;
        private String Title;
        private int TIMES_RENEWED;
    
        public boolean CanRenew() {
            return TIMES_RENEWED < maxRenewals;
        }
    }
  2. Đoạn mã này có biên dịch được không? Nếu có, nó in ra gì?
    public class thermostat {
        public static final int Max_Temp = 80;
    
        public static void main(String[] args) {
            int T = 68 + 15;
            if (T > Max_Temp) {
                T = Max_Temp;
            }
            System.out.println("Set to " + T);
        }
    }
  3. Tìm ba lỗi trong chú thích này:
    /*
     * Sets the volume.
     * @param the new volume, from 0 to 10
     * @return the volume
     */
    public void setVolume(int level) {
  4. Viết một phương thức static boxesNeeded(int cookies, int perBox) trả về cần bao nhiêu hộp, tính hộp đầy một phần như một hộp nguyên. Hãy viết cho nó một chú thích Javadoc hoàn chỉnh.
  5. Một tệp bắt đầu bằng một chú thích Javadoc về lớp, rồi import java.util.Scanner;, rồi public class Kiosk {, mà hàm tạo và các phương thức đều có Javadoc đúng. javadoc sẽ nói gì về lớp, và cách sửa là gì?
  6. Đoạn này cho lỗi gì, và cách sửa thông thường là gì?
    public class OrderQueue {
        public static void main(String[] args) {
            ArrayList<String> orders = new ArrayList<>();
            orders.add("oat latte");
            System.out.println(orders.size() + " order waiting");
        }
    }

Lời giải#

  1. LibraryBook, MAX_RENEWALS, title, timesRenewed, canRenew. Trình biên dịch không bắt buộc cái nào. Nhưng một lớp public được đổi tên thì cần đổi tên tệp: LibraryBook.java.
  2. Nó biên dịch được: mọi tên đều hợp lệ và được dùng nhất quán, chỉ là không đúng quy ước. 68 + 15 = 83, lớn hơn 80, nên T trở thành 80.thermostat.java
    public class thermostat {
        public static final int Max_Temp = 80;
    
        public static void main(String[] args) {
            int T = 68 + 15;
            if (T > Max_Temp) {
                T = Max_Temp;
            }
            System.out.println("Set to " + T);
        }
    }
    Set to 80
  3. Nó mở đầu bằng /*, nên javadoc bỏ qua; @param phải bắt đầu bằng tên level; và phương thức void không có @return:
    /**
     * Sets the volume.
     *
     * @param level the new volume, from 0 to 10
     */
    public void setVolume(int level) {
  4. Hai tham số, hai dòng @param; trả về một int, một @return. Cộng thêm perBox - 1 trước khi chia sẽ làm tròn lên; 0 chiếc bánh quy cho 11 / 12 = 0.Bakery.java
    public class Bakery {
        /**
         * Returns how many boxes are needed to pack all the cookies.
         * A box that is only partly full still counts as one box.
         *
         * @param cookies the number of cookies to pack, 0 or more
         * @param perBox how many cookies fit in one box, at least 1
         * @return the number of boxes needed
         */
        public static int boxesNeeded(int cookies, int perBox) {
            return (cookies + perBox - 1) / perBox;
        }
    
        public static void main(String[] args) {
            System.out.println(boxesNeeded(25, 12));
            System.out.println(boxesNeeded(24, 12));
            System.out.println(boxesNeeded(0, 12));
        }
    }
    3
    2
    0
  5. warning: no comment cho lớp. Một dòng import không thể mang chú thích Javadoc, nên chú thích phía trên nó không ghi chú cho gì cả. Hãy đặt import lên trước, để chú thích nằm ngay phía trên public class Kiosk.
  6. cannot find symbol cho class ArrayList, vì nó nằm trong java.util, không được import tự động. Thêm import java.util.ArrayList; ở đầu, hoặc viết java.util.ArrayList ở cả hai chỗ.OrderQueue.java
    public class OrderQueue {
        public static void main(String[] args) {
            ArrayList<String> orders = new ArrayList<>();
            orders.add("oat latte");
            System.out.println(orders.size() + " order waiting");
        }
    }
    OrderQueue.java:3: error: cannot find symbol
            ArrayList<String> orders = new ArrayList<>();
            ^
      symbol:   class ArrayList
      location: class OrderQueue
    OrderQueue.java:3: error: cannot find symbol
            ArrayList<String> orders = new ArrayList<>();
                                           ^
      symbol:   class ArrayList
      location: class OrderQueue
    2 errors

Danh sách kiểm tra trước khi thi#

Đây là các mục trong danh sách chủ đề Bài thi 1 của môn học mà bài hướng dẫn này đề cập. Chỉ đánh dấu mỗi mục khi bạn làm được mà không cần nhìn.

  • ☐  Tôi có thể đặt tên một lớp, phương thức, biến và hằng số đúng kiểu, và biết trình biên dịch chấp nhận mọi kiểu.
  • ☐  Tôi có thể phân biệt //, /* */ và /** */ và nói được loại nào javadoc đọc.
  • ☐  Tôi có thể đặt một chú thích Javadoc và viết @author, @version, @param và @return đúng cách.
  • ☐  Tôi có thể giải thích vì sao String không cần import mà Scanner thì cần, và vì sao một lớp như LoyaltyCard không chứa Scanner.

Tự kiểm tra trong ứng dụng Kestrel Exams miễn phí

16 câu hỏi luyện tập về quy ước đặt tên và Javadoc, mọi đáp án mã đều đã được kiểm tra bằng cách biên dịch và chạy. Miễn phí, dùng được khi không có mạng, không cần tài khoản.

Luyện tập quy ước đặt tên và Javadoc →

Câu hỏi thường gặp#

Trong Java, /* */ và /** */ khác nhau như thế nào?

Với trình biên dịch thì không khác gì: cả hai đều bị bỏ qua. Công cụ javadoc chỉ đọc những chú thích bắt đầu bằng /** và biến chúng thành tài liệu HTML. Một chú thích bắt đầu bằng /* là chú thích thông thường, kể cả khi bên trong có các thẻ như @return.

Java có bắt buộc quy ước đặt tên như camelCase không?

Không. Trình biên dịch chấp nhận một lớp tên loyaltycard và một phương thức tên ADD. Nó chỉ kiểm tra rằng tên hợp lệ, rằng chúng được viết cùng một cách mỗi lần (Java phân biệt chữ hoa chữ thường), và rằng tên của một lớp public khớp với tên tệp.

Java dùng những quy ước đặt tên nào?

Lớp dùng PascalCase (LoyaltyCard). Biến, trường, tham số và phương thức dùng camelCase (ownerName, addStamp). Hằng số, tức là các trường static final, dùng UPPER_SNAKE_CASE (STAMPS_PER_FREE_DRINK). Tên gói (package) viết toàn bộ bằng chữ thường (java.util).

Phương thức void có cần thẻ @return trong Javadoc không?

Không. @return mô tả giá trị mà phương thức trả về, còn phương thức void không trả về gì. Hàm tạo cũng không có thẻ này; javadoc báo "invalid use of @return". Mỗi tham số vẫn có một dòng @param.

Làm sao biến các chú thích Javadoc thành trang HTML?

Chạy công cụ javadoc trong JDK, ví dụ javadoc -d docs LoyaltyCard.java, rồi mở docs/index.html trong trình duyệt. Thêm -author và -version để hiển thị các thẻ đó.

Đề xuất chỉnh sửa

Có chỗ nào chưa rõ? Có chủ đề nào bạn mong chúng tôi viết? Hãy cho chúng tôi biết. Chúng tôi đọc mọi tin nhắn, và một lời đề nghị là cách nhanh nhất để có một bài hướng dẫn mới: nhiều bài trong số này ra đời vì có người đã hỏi.