Tài liệu hóa với Nhận xét
Đã giới thiệu| English | Ý nghĩa |
|---|---|
| comment/ˈkɒment/ | Ghi chú |
Một chú thích không sửa chữa được công thức đang hoạt động
- Đối với giá 100, biểu thức
total = price * 10 / 100;vẫn tính ra 10 ngay cả khi có chú thích ghi “số tiền phải trả sau khi giảm mười phần trăm”. Chỉnh sửa phần giải thích đó sẽ không khiến biểu thức tính ra 90. - Thay đổi biểu thức đang hoạt động thành
price * 90 / 100để tính toán số tiền thanh toán mong muốn trong ví dụ số nguyên này. Chú thích có thể tiết lộ chính sách dự định; hãy xác minh xem mã code có thực hiện đúng chính sách đó hay không.
Xác định văn bản bị loại bỏ khỏi mã code
//bắt đầu một dòng chú thích kết thúc ở dấu xuống dòng./*bắt đầu một khối chú thích kết thúc ở ký tự*/tiếp theo; các khối chú thích không được lồng nhau. Các ký tự giới hạn nằm bên trong chuỗi ký tự chỉ là văn bản, do đó"https://example.com"không bắt đầu một dòng chú thích.- Văn bản comment không được thực thi như các câu lệnh Java. Việc thêm một giải thích riêng biệt sẽ giữ nguyên biểu thức đang hoạt động; đặt
//trước một phép gán đang hoạt động sẽ loại bỏ phép gán đó khỏi mã đã biên dịch và có thể làm thay đổi hành vi.
Đặt các thẻ Javadoc trên các dòng riêng biệt
- Một comment tài liệu
/** ... */ngay trước một khai báo có thể được xử lý bởi Javadoc. Phần tóm tắt của nó giải thích thao tác; các thẻ khối như@paramvà@returnbắt đầu trên các dòng mới sau khoảng trắng tùy chọn và*. - Lớp hoàn chỉnh dưới đây tài liệu hóa bán kính không âm và trả về diện tích hình tròn của nó. Các thẻ mô tả đầu vào, đầu ra và đầu vào bị từ chối; vì chỉ có comment đơn lẻ thì không áp đặt được điều kiện tiên quyết, nên phương pháp kiểm tra rõ ràng các bán kính âm.
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadoc nhận diện @param là một block tag khi nó nằm xen kẽ ngay sau văn bản tóm tắt trên cùng một dòng.
Độ khó 1/5 · 100 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
Một block tag bắt đầu ở dòng mới riêng biệt, sau khoảng trắng tùy chọn và dấu sao (*) dẫn đầu tùy chọn. Hãy sử dụng dạng comment đa dòng như hình minh họa.
Giải thích quyết định mà người đọc không thể thấy
- Một comment giảm giá hữu ích có thể nêu “thanh toán là 90% giá niêm yết; bài tập này sử dụng giá nguyên”. Điều này giải thích chính sách và giả thiết, trong khi
// multiply by 90chỉ lặp lại một thao tác. - Tóm tắt của một phương pháp công khai vẫn hữu ích ngay cả khi thân phương pháp ngắn: người gọi cần hợp đồng của nó mà không phải nghiên cứu phần triển khai. Ưu tiên các giải thích cung cấp ngữ cảnh còn thiếu hơn là tuyên bố rằng mọi comment mô tả đều thừa thãi.
Khi một chương trình Java chạy, các nhận xét là...
Độ khó 1/5 · 100 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
Nhận xét dành cho con người — Java bỏ qua chúng.
Cái nào bắt đầu một nhận xét dòng đơn trong Java?
Độ khó 1/5 · 100 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
// chạy đến cuối dòng; /* */ là khối.
Kiểu nhận xét nào mà các công cụ chuyển đổi thành tài liệu API?
Độ khó 1/5 · 100 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
Javadoc /** */ với @param/@return tạo ra docs API.
Viết thêm dòng chú thích giải thích bên cạnh công thức đang hoạt động không thay đổi thì không sửa được lỗi tính toán của nó.
Độ khó 1/5 · 100 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
Sai: các dòng chú thích giải thích không phải là câu lệnh. Việc comment out (bỏ hiệu lực) một câu lệnh có thể thay đổi hành vi, nhưng điều đó đồng nghĩa với việc thay đổi đoạn code đang được kích hoạt.
Nhận xét tốt giải thích TẠI SAO, thay vì nói lại những gì code rõ ràng làm.
Độ khó 1/5 · 100 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
Đánh dấu ý đồ, không phải những điều hiển nhiên.
Kiểm tra tài liệu đối chiếu với phần triển khai
- Giả sử comment hứa hẹn rằng bán kính âm sẽ bị từ chối, nhưng bộ bảo vệ bị xóa. Tài liệu giờ đây trở nên sai lệch mặc dù vẫn sinh thành thành công; hãy thử nghiệm cả đầu vào âm và bán kính thông thường.
- Khi hành vi thay đổi, hãy cập nhật phần triển khai, các kiểm tra và tài liệu của nó cùng lúc. Sinh trang API chỉ xác minh cú pháp tài liệu, chứ không phải tính đúng đắn của mọi tuyên bố bên trong.
/** Returns an area. @param r radius @return area */ không đặt các thẻ khối ở điểm bắt đầu dòng yêu cầu. Hãy sử dụng dạng đa dòng ở trên, sau đó kiểm tra các phần tham số và trả về đã sinh ra. Các comment giải thích thông thường không phải là sửa lỗi có thể thực thi được.
Một nhận xét hữu ích hay không?
Nhận xét tốt giải thích ý đồ, không phải những điều hiển nhiên. Sắp xếp từng cái một.
Dự đoán một phép gán bị(comment) commented-out
- Bắt đầu với
int x = 1;. Vớix = 5;đang hoạt động, in x sẽ cho 5; thay thế dòng đó bằng// x = 5;sẽ in ra 1. Thay đổi những câu lệnh nào đang hoạt động khác với việc thêm ghi chú cạnh một câu lệnh không thay đổi. - Xem xét ba câu hỏi riêng biệt: phép tính đang hoạt động có đúng không, comment có giải thích chính xác không, và các thẻ Javadoc có được phân tách vào đúng phần mong muốn không? Việc biên dịch thành công không trả lời tất cả ba vấn đề.
Comment giải thích code cho người đọc. Các ký hiệu ngăn cách có thể loại trừ câu lệnh, trong khi ghi chú cạnh code đang hoạt động không sửa được phép tính. Các thẻ khối Javadoc bắt đầu trên các dòng riêng biệt; hãy giữ hợp đồng tài liệu nhất quán với phần triển khai.
For a price of 100, type the amount paid after a ten percent discount.
Độ khó 1/5 · 100 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; tiếp theo bởi // x = 5; trên một dòng riêng biệt. Giá trị của x sẽ được in ra là gì?
Độ khó 2/5 · 140 xu + một phần thưởng nhỏ cho lần hoàn thành đầu tiên trong ngày
Việc gán cho 5 bị loại bỏ bởi dòng chú thích đơn; x vẫn giữ 1.