Câu trả lời:
Hình thức đầu tiên được gọi là Javadoc . Bạn sử dụng điều này khi bạn đang viết API chính thức cho mã của mình, được tạo bởi javadoccông cụ. Ví dụ: trang API Java 7 sử dụng Javadoc và được tạo bởi công cụ đó.
Một số yếu tố phổ biến bạn thấy trong Javadoc bao gồm:
@param: điều này được sử dụng để chỉ ra tham số nào đang được truyền cho một phương thức và giá trị mà chúng dự kiến sẽ có
@return: điều này được sử dụng để chỉ ra kết quả mà phương thức sẽ trả lại
@throws: điều này được sử dụng để chỉ ra rằng một phương thức đưa ra một ngoại lệ hoặc lỗi trong trường hợp đầu vào nhất định
@since: cái này được sử dụng để chỉ ra phiên bản Java sớm nhất mà lớp hoặc hàm này có sẵn trong
Ví dụ, đây là Javadoc cho comparephương pháp Integer:
/**
* Compares two {@code int} values numerically.
* The value returned is identical to what would be returned by:
* <pre>
* Integer.valueOf(x).compareTo(Integer.valueOf(y))
* </pre>
*
* @param x the first {@code int} to compare
* @param y the second {@code int} to compare
* @return the value {@code 0} if {@code x == y};
* a value less than {@code 0} if {@code x < y}; and
* a value greater than {@code 0} if {@code x > y}
* @since 1.7
*/
public static int compare(int x, int y) {
return (x < y) ? -1 : ((x == y) ? 0 : 1);
}Hình thức thứ hai là một bình luận khối (nhiều dòng). Bạn sử dụng điều này nếu bạn muốn có nhiều dòng trong một bình luận.
Tôi sẽ nói rằng bạn chỉ muốn sử dụng hình thức sau một cách tiết kiệm ; nghĩa là, bạn không muốn làm quá tải mã của mình bằng các nhận xét chặn không mô tả hành vi nào mà phương thức / hàm phức tạp được cho là có.
Vì Javadoc là mô tả nhiều hơn về hai và bạn có thể tạo tài liệu thực tế do sử dụng nó, nên sử dụng Javadoc sẽ thích hợp hơn với các nhận xét khối đơn giản.
Đối với ngôn ngữ lập trình Java , không có sự khác biệt giữa hai ngôn ngữ này . Java có hai loại bình luận: bình luận truyền thống ( /* ... */) và bình luận cuối dòng ( // ...). Xem Đặc tả ngôn ngữ Java . Vì vậy, đối với ngôn ngữ lập trình Java, cả hai /* ... */và /** ... */đều là các thể hiện của các nhận xét truyền thống và cả hai đều được xử lý chính xác giống nhau bởi trình biên dịch Java, nghĩa là chúng bị bỏ qua (hoặc chính xác hơn: chúng được coi là khoảng trắng).
Tuy nhiên, là một lập trình viên Java, bạn không chỉ sử dụng trình biên dịch Java. Bạn sử dụng toàn bộ chuỗi công cụ, bao gồm trình biên dịch, IDE, hệ thống xây dựng, v.v. Và một số công cụ này diễn giải mọi thứ khác với trình biên dịch Java. Cụ thể, các /** ... */bình luận được giải thích bởi công cụ Javadoc, được bao gồm trong nền tảng Java và tạo tài liệu. Công cụ Javadoc sẽ quét tệp nguồn Java và diễn giải các phần giữa /** ... */làm tài liệu.
Điều này tương tự với các thẻ như FIXMEvà TODO: nếu bạn bao gồm một nhận xét như // TODO: fix thishoặc // FIXME: do that, hầu hết các IDE sẽ làm nổi bật các nhận xét đó để bạn không quên chúng. Nhưng đối với Java, họ chỉ là những bình luận.
javadoccông cụ không thể giải thích điều gì đó.
Đọc phần 3.7 của JLS giải thích rõ tất cả những gì bạn cần biết về các nhận xét trong Java.
Có hai loại ý kiến:
- /* bản văn */
Một nhận xét truyền thống: tất cả văn bản từ các ký tự ASCII / * đến các ký tự ASCII * / bị bỏ qua (như trong C và C ++).
- //bản văn
Nhận xét cuối dòng: tất cả văn bản từ các ký tự ASCII // đến cuối dòng bị bỏ qua (như trong C ++).
Về câu hỏi của bạn,
Cái đầu tiên
/**
*
*/được sử dụng để khai báo Javadoc Technology .
Javadoc là một công cụ phân tích các khai báo và nhận xét tài liệu trong một tập hợp các tệp nguồn và tạo ra một tập các trang HTML mô tả các lớp, giao diện, hàm tạo, phương thức và trường. Bạn có thể sử dụng tài liệu Javadoc để tùy chỉnh đầu ra Javadoc. Một doclet là một chương trình được viết bằng API Doclet chỉ định nội dung và định dạng của đầu ra sẽ được tạo bởi công cụ. Bạn có thể viết một doclet để tạo bất kỳ loại đầu ra tệp văn bản nào, chẳng hạn như HTML, SGML, XML, RTF và MIF. Oracle cung cấp một doclet tiêu chuẩn để tạo tài liệu API định dạng HTML. Tài liệu cũng có thể được sử dụng để thực hiện các tác vụ đặc biệt không liên quan đến sản xuất tài liệu API.
Để biết thêm thông tin về việc Doclettham khảo API .
Cái thứ hai, như được giải thích rõ ràng trong JLS, sẽ bỏ qua tất cả các văn bản giữa /*và */do đó được sử dụng để tạo các bình luận đa dòng.
Một số điều khác bạn có thể muốn biết về các nhận xét trong Java
/* and */ không có ý nghĩa đặc biệt trong các bình luận bắt đầu bằng // .// không có ý nghĩa đặc biệt trong các bình luận bắt đầu bằng /* or /** .Do đó, văn bản sau đây là một nhận xét hoàn chỉnh duy nhất:
/* this comment /* // /** ends here: */Tôi không nghĩ rằng các câu trả lời hiện có đã giải quyết thỏa đáng phần này của câu hỏi:
Khi nào tôi nên sử dụng chúng?
Nếu bạn đang viết một API sẽ được xuất bản hoặc sử dụng lại trong tổ chức của mình, bạn nên viết các bình luận Javadoc toàn diện cho mọi publiclớp, phương thức và trường, cũng như protectedcác phương thức và trường của các finallớp không . Javadoc nên bao gồm mọi thứ không thể được chuyển tải bằng chữ ký phương thức, chẳng hạn như điều kiện tiên quyết, hậu điều kiện, đối số hợp lệ, ngoại lệ thời gian chạy, cuộc gọi nội bộ, v.v.
Nếu bạn đang viết một API nội bộ (một API được sử dụng bởi các phần khác nhau của cùng một chương trình), Javadoc được cho là ít quan trọng hơn. Nhưng vì lợi ích của các lập trình viên bảo trì, bạn vẫn nên viết Javadoc cho bất kỳ phương thức hoặc trường nào trong đó việc sử dụng đúng hoặc ý nghĩa không rõ ràng ngay lập tức.
"Tính năng sát thủ" của Javadoc là nó được tích hợp chặt chẽ với Eclipse và các IDE khác. Một nhà phát triển chỉ cần di con trỏ chuột lên một mã định danh để tìm hiểu mọi thứ họ cần biết về nó. Liên tục đề cập đến tài liệu trở thành bản chất thứ hai cho các nhà phát triển Java có kinh nghiệm, giúp cải thiện chất lượng mã của chính họ. Nếu API của bạn không được ghi lại bằng Javadoc, các nhà phát triển có kinh nghiệm sẽ không muốn sử dụng nó.
Các nhận xét trong danh sách Mã Java sau đây là các ký tự màu xám:
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}Ngôn ngữ Java hỗ trợ ba loại ý kiến:
/* text */Trình biên dịch bỏ qua mọi thứ từ /*đến */.
/** documentation */Điều này chỉ ra một nhận xét tài liệu (viết tắt của doc, viết tắt). Trình biên dịch bỏ qua loại bình luận này, giống như nó bỏ qua các bình luận sử dụng /*và */. Công cụ javadoc JDK sử dụng các nhận xét doc khi chuẩn bị tài liệu được tạo tự động.
// textTrình biên dịch bỏ qua mọi thứ từ //đến cuối dòng.
Bây giờ liên quan đến khi nào bạn nên sử dụng chúng:
Sử dụng // textkhi bạn muốn bình luận một dòng mã.
Sử dụng /* text */ khi bạn muốn bình luận nhiều dòng mã.
Sử dụng /** documentation */ khi bạn muốn thêm một số thông tin về chương trình có thể được sử dụng để tạo tài liệu chương trình tự động.
Đầu tiên là dành cho Javadoc mà bạn xác định ở đầu các lớp, giao diện, phương thức, v.v. Bạn có thể sử dụng Javadoc làm tên gợi ý để ghi lại mã của bạn về những gì lớp làm hoặc phương thức nào, v.v. và tạo báo cáo về nó.
Thứ hai là bình luận khối mã. Ví dụ, bạn có một số khối mã mà bạn không muốn trình biên dịch diễn giải thì bạn sử dụng nhận xét khối mã.
một cái khác là // cái này bạn sử dụng ở mức câu lệnh để xác định dòng tiến trình mã được cho là phải làm gì.
Có một số khác cũng như // TODO, điều này sẽ đánh dấu rằng bạn muốn làm gì đó sau này ở nơi đó
// FIXME bạn có thể sử dụng khi bạn có một số giải pháp tạm thời nhưng bạn muốn truy cập sau và làm cho nó tốt hơn.
Hi vọng điêu nay co ich
Java hỗ trợ hai loại ý kiến:
/* multiline comment */: Trình biên dịch bỏ qua mọi thứ từ /*đến */. Nhận xét có thể trải dài trên nhiều dòng.
// single line: Trình biên dịch bỏ qua mọi thứ từ //cuối dòng.
Một số công cụ như javadoc sử dụng một nhận xét đa dòng đặc biệt cho mục đích của họ. Ví dụ: /** doc comment */một nhận xét tài liệu được sử dụng bởi javadoc khi chuẩn bị tài liệu được tạo tự động, nhưng đối với Java, đó là một nhận xét đa dòng đơn giản.
/** .. */chỉ là một nhận xét đa dòng thông thường, và ký tự đầu tiên bên trong nó là dấu hoa thị.