Tự động ghi lại mã Java của bạn với Javadoc

Nếu bạn thực hiện bất kỳ loại lập trình nào, bạn sẽ nhận thức rõ rằng một trong những nhiệm vụ tẻ nhạt nhất liên quan là ghi lại mã của bạn. Cho dù bạn thấy nó hơi khó chịu hay một công việc mà bạn phải đối mặt với sự sợ hãi tuyệt đối, thì tài liệu mã là điều cần thiết. Những người khác cần hiểu cách mã của bạn hoạt động và bạn thậm chí có thể là một trong số họ nếu bạn đang đọc nó vào một ngày sau đó!

Java cung cấp một giải pháp tích hợp cho vấn đề một cách thuận tiện: Javadoc.

Javadoc có thể giúp bạn ghi lại mã của mình một cách tự động

Hy vọng rằng bạn đã làm theo các phương pháp viết mã tốt và bao gồm các nhận xét giải thích trong mã của bạn. Mặc dù loại bình luận trong mã này chắc chắn hữu ích, nhưng nó không thực sự cung cấp bất cứ thứ gì có thể so sánh được với sách hướng dẫn.

Chắc chắn, một lập trình viên khác có thể xem qua mã của bạn và đọc về các lớp, phương thức và hàm cụ thể trước mặt anh ta. Tuy nhiên, rất khó để có một cái nhìn tổng quan tốt về tất cả các đoạn mã hoặc tìm thấy các hàm có thể hữu ích khi bạn không biết chúng tồn tại. Javadoc nhằm giải quyết vấn đề đó.

Javadoc sẽ tự động tạo ra một hướng dẫn sử dụng HTML chi tiết và thân thiện với người đọc cho tất cả mã của bạn. Hơn hết, nó thực hiện điều đó bằng cách sử dụng các bình luận mã mà bạn có thể đã viết.

Chính xác thì Javadoc là gì và nó hoạt động như thế nào?

Javadoc là một chương trình độc lập đi kèm với các bản phát hành bộ phát triển Java (JDK) của Oracle. Trên thực tế, bạn không thể tải xuống riêng lẻ. Khi bạn tải xuống và cài đặt một trong các phiên bản JDK của Oracle, nó cũng sẽ cài đặt Javadoc.

Khi bạn chạy nó, Javadoc tạo tài liệu HTML từ các nhận xét được định dạng đặc biệt trong mã nguồn Java của bạn. Quá trình này tạo ra nhiều tài liệu hữu ích hơn, dễ đọc hơn đồng thời khuyến khích các phương pháp hay nhất.

Tóm lại, Javadoc giúp bạn có thể viết mã và tài liệu của nó cùng một lúc. Nó đơn giản hóa quy trình làm việc của bạn và cho phép bạn sử dụng thời gian hiệu quả hơn.

Javadoc hoạt động bằng cách phân tích cú pháp các nhận xét được định dạng đặc biệt trong mã của bạn và chuyển đổi chúng thành đầu ra HTML. Thay đổi duy nhất bạn thực sự cần thực hiện là thêm một số chuỗi nhất định vào nhận xét của bạn. Những điều này cho Javadoc biết những gì bạn muốn đưa vào tài liệu cuối cùng.

Nhận xét Javadoc phải ngay trước khai báo lớp, trường, hàm tạo hoặc phương thức. Bản thân nhận xét phải:

• Bắt đầu bằng ba ký tự / **.
• Bao gồm dấu hoa thị ở đầu mỗi dòng mới.
• Đóng bằng hai ký tự * /.

Trong phần nhận xét, bạn có thể đưa HTML vào đầu ra cuối cùng và bao gồm các thẻ sẽ tạo liên kết đến các phần có liên quan trong cơ sở mã của bạn. Bạn thậm chí có thể sử dụng những thứ như thẻ hình ảnh HTML để đưa hình ảnh vào tài liệu cuối cùng. Một khi bạn đã quen với định dạng và các thẻ có sẵn, việc viết các bình luận như vậy thật dễ dàng.

Dưới đây là một ví dụ để minh họa các nhận xét Javadoc đơn giản mô tả một hàm lấy hình ảnh từ URL và in ra màn hình. Nhận xét ngay lập tức đứng trước hàm và mô tả chức năng của nó. Khối nhận xét này cũng sử dụng ba thẻ dành riêng cho phần: @param, @trở vềvà @hiểu.

* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}

Khi Javadoc xử lý đoạn mã trên, nó sẽ tạo ra một trang web tương tự như sau:

Một trình duyệt hiển thị đầu ra Javadoc giống như cách nó hiển thị bất kỳ tài liệu HTML nào. Javadoc bỏ qua khoảng trắng thừa và dấu ngắt dòng trừ khi bạn sử dụng thẻ HTML để tạo khoảng trắng đó.

@Tags được sử dụng ở cuối nhận xét tạo ra Thông số, Lợi nhuậnvà Xem thêm phần mà bạn nhìn thấy.

Bạn nên làm theo @param với tên của thông số, khoảng trắng và mô tả về nó. Trong trường hợp trên, có hai tham số: url và Tên. Lưu ý rằng cả hai đều xuất hiện dưới cùng một tiêu đề Tham số trong đầu ra tài liệu. Bạn có thể liệt kê nhiều tham số cần thiết cho hàm hoặc phương thức mà bạn đang mô tả.

Các @trở về gắn thẻ tài liệu giá trị mà hàm trả về, nếu có. Nó có thể là một mô tả đơn giản một từ hoặc nhiều câu, tùy thuộc vào hoàn cảnh.

Các @hiểu thẻ cho phép bạn gắn thẻ các chức năng khác có liên quan hoặc có liên quan. Trong trường hợp này, thẻ @see đề cập đến một chức năng khác được gọi đơn giản là Hình ảnh. Lưu ý rằng các tham chiếu được tạo bằng thẻ này là các liên kết có thể nhấp, cho phép người đọc chuyển đến mục được tham chiếu trong HTML cuối cùng.

Có nhiều thẻ hơn như @version, @author, @exception và những thẻ khác. Khi được sử dụng đúng cách, các thẻ giúp liên kết các mục với nhau và giúp bạn có thể điều hướng qua tài liệu một cách dễ dàng.

Chạy Javadoc trên mã nguồn của bạn

Bạn gọi Javadoc trên dòng lệnh. Bạn có thể chạy nó trên các tệp đơn, toàn bộ thư mục, gói java hoặc trên danh sách các tệp riêng lẻ. Theo mặc định, Javadoc sẽ tạo các tệp tài liệu HTML trong thư mục nơi bạn nhập lệnh. Để nhận trợ giúp về các lệnh cụ thể có sẵn, chỉ cần nhập:

javadoc 

Để biết chính xác những gì Javadoc có thể làm chi tiết hơn, hãy xem tài liệu chính thức từ Oracle. Để tạo một bộ tài liệu nhanh trên một tệp hoặc thư mục, bạn có thể nhập javadoc trên dòng lệnh theo sau là tên tệp hoặc ký tự đại diện.

javadoc ~/code/filename.java
javadoc ~/code/*.java

Trên đây là danh sách các tập tin và thư mục mà Javadoc đã tạo. Như bạn có thể thấy, có khá nhiều người trong số họ. Vì lý do này, bạn nên chắc chắn rằng bạn không ở trong cùng thư mục với mã nguồn của bạn khi bạn chạy chương trình. Làm như vậy có thể tạo ra một mớ hỗn độn.

Để xem các tài liệu mới tạo của bạn, chỉ cần mở index.html tệp trong trình duyệt ưa thích của bạn. Bạn sẽ nhận được một trang như sau:

Đây là tài liệu cho một lớp Java ngắn, duy nhất để chứng minh kết quả đầu ra. Tiêu đề hiển thị tên của lớp cũng như các phương thức có trong nó. Cuộn xuống sẽ hiển thị các định nghĩa chi tiết hơn về từng phương thức của lớp.

Như bạn có thể thấy, đối với bất kỳ loại dự án Java nào, đặc biệt là những dự án lớn với hàng nghìn dòng mã, loại tài liệu này là vô giá. Sẽ là một thách thức khi tìm hiểu về một cơ sở mã lớn bằng cách đọc qua mã nguồn của nó. Các trang javadoc làm cho quá trình này nhanh hơn và dễ dàng hơn nhiều.

Javadoc có thể giúp bạn giữ cho mã Java và tất cả các tài liệu liên quan được sắp xếp và dễ sử dụng. Cho dù bạn đang làm điều đó vì tương lai lãng quên của mình hay để làm mọi thứ dễ dàng hơn cho một nhóm lớn, Javadoc là một công cụ mạnh mẽ có thể thay đổi cách bạn viết và tương tác với các dự án mã hóa Java của bạn.

Đọc tiếp