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.
Đâ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.
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ì.
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ểu | Trông như thế nào | Dùng cho | Trên thẻ |
|---|---|---|---|
| PascalCase | viết hoa mọi từ | lớp | LoyaltyCard |
| camelCase | từ đầu viết thường, các từ sau viết hoa | biến, trường, tham số, phương thức | ownerName, addStamp |
| UPPER_SNAKE_CASE | toàn chữ hoa, dấu gạch dưới giữa các từ | hằng số | STAMPS_PER_FREE_DRINK |
| chữ thường | toàn chữ thường, các phần nối với nhau bằng dấu chấm | gó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 đổ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.javapublic 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().
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ệ.
2ndCardkhông hợp lệ, vì tên không thể bắt đầu bằng chữ số;second_cardhợ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ớicannot find symbol, chính là lỗi bạn sẽ gặp vớiScannerbên dưới. Đó cũng là lý dostringvớ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
publicphả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ạng | Viết là | Dùng cho |
|---|---|---|
| Chú thích dòng | // đến hết dòng | mộ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 sao | tà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.
/**
* 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 ....
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ó.
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.
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ã.
/**
* 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).
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 đó.
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, name | khô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, drinks | một |
Một setter void (phương thức thay đổi một trường) có @param và không có @return.
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
*/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.
/**
* 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.
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.
Đừ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 < 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#
- PascalCase, camelCase, UPPER_SNAKE_CASE và tên gói viết chữ thường.
- 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.
/** */là loại chú thích duy nhất javadoc đọc.- Javadoc nằm ngay phía trên thứ nó ghi chú.
@authorvà@version.java.langlà tự động;Scannercần import và thuộc về chương trình.@paramcho mỗi tham số,@returnchỉ khi có giá trị trả về.- HTML bên trong Javadoc.
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ứcvoidhoặc hàm tạo. Cả hai đều không trả về giá trị; javadoc báoinvalid 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.utilkhông tự động. (ImportStringkhông gây hại nhưng không bao giờ cần:java.langlà tự động.) - Một trường
Scannertrong một lớp nhưLoyaltyCard. Hãy đọc đầu vào trongmain; 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ã đó.
- Đổ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; } } - Đ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); } } - 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) { - 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. - 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ồipublic 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ì? - Đ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#
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.- 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
Ttrở thành 80.thermostat.javapublic 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 - Nó mở đầu bằng
/*, nên javadoc bỏ qua;@paramphải bắt đầu bằng tênlevel; và phương thứcvoidkhông có@return:/** * Sets the volume. * * @param level the new volume, from 0 to 10 */ public void setVolume(int level) { - Hai tham số, hai dòng
@param; trả về mộtint, một@return. Cộng thêmperBox - 1trước khi chia sẽ làm tròn lên; 0 chiếc bánh quy cho11 / 12= 0.Bakery.javapublic 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 warning: no commentcho lớp. Một dòngimportkhô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ênpublic class Kiosk.cannot find symbolchoclass ArrayList, vì nó nằm trongjava.util, không được import tự động. Thêmimport java.util.ArrayList;ở đầu, hoặc viếtjava.util.ArrayListở cả hai chỗ.OrderQueue.javapublic 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,@paramvà@returnđúng cách. - ☐ Tôi có thể giải thích vì sao
Stringkhông cần import màScannerthì cần, và vì sao một lớp nhưLoyaltyCardkhông chứaScanner.
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ẻ đó.
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.