Chú thích trong Java

1. Chú thích là gì?

Chú thích (comment) cho mã nguồn được khuyến khích trong các tài liệu về lập trình. Nó giúp giải thích nội dung của đoạn mã bằng ngôn ngữ tự nhiên, giúp giảm đi thời gian phải đọc lại mã nguồn khi sử dụng.

Các văn bản sử dụng trong ghi chú sẽ không được trình biên dịch của Java biên dịch. Chúng chỉ có tác dụng cho con người đọc để hiểu. Máy tính sẽ không quan tâm đến nó. Thường thì các ghi chú này sử dụng Tiếng Anh. Vì hầu hết các tên phương thức, hàm và tên lớp trong mã nguồn điều sử dụng Tiếng Anh.

Nếu bạn là một Lập trình viên thì không thể nào không biết Tiếng Anh? Nhưng đó không phải là bắt buộc. Ta có thể ghi chú thích bằng Tiếng Việt hay bất cứ ngôn ngữ nào mà ta thích miễn là đội ngũ của bạn đọc nó có thể hiểu.

Tôi từng làm ứng dụng cho khách hàng ở nhật thì thấy họ cũng trung thành với ngôn ngữ của họ. Những ghi chú trong mã nguồn sử dụng Tiếng Nhật. Không quan trọng miễn sau đó là ngôn ngữ tự nhiên (người không chuyên có thể đọc hiểu).

Ghi chú được sử dụng ở nhiều nơi nhưng tôi thấy có 3 nơi chính mà ta cần quan tâm. Khối mã trong thân phương thức, mô tả chức năng của một phương thức ở đầu phương thức, giải thích công dụng của một lớp ở đầu của lớp.

Riêng chức năng ghi chú trên phương thức và lớp sẽ được các trình soạn thảo (phần mềm sử dụng để viết mã nguồn hỗ trợ cho các ghi chú này hiện trong lúc lập trình). Công dụng này sẽ được đề cập thêm trong phần 2.

Với tôi, công dụng chính của ghi chú là giúp tôi biết được khối mã lệnh dùng để làm gì? Tôi không cần phải đọc chi tiết vào mã nguồn để hiểu. Đôi khi đọc vào mã lệnh cũng không hiểu nhiều nếu ta không phải là người chuyên về ngôn ngữ lập trình đó hay không phải là người hiểu nhiều về nghiệp vụ của nó. Ghi chú là một giải pháp cứu cánh.

Với công dụng trên, ta có thể dể dàng trong trao đổi với các thành viên nhóm thông qua các ghi chú mà không cần phải giải thích trực tiếp nhiều. Không chỉ có tác dụng để các thành viên trong nhóm hiểu nó mà kể tác giả cũng có thể hiểu nó. Nếu ta đã viết mã lệnh trong đã lâu nhưng ta cần bảo trì thì ghi chú sẽ là một phương tiện giúp tốc độ làm việc nhanh hơn.

2. Dạng ghi chú trong Java

Ngôn ngữ lập trình nào cũng quy định cách viết ghi chú mã nguồn của họ. Quy định này phục thuộc vào trình biên dịch của nó. Trình biên dịch phải biết ở đâu bắt đầu ghi chú ở đâu kết thúc ghi chú để bỏ qua. Ta không thể đề cập hết, do đó phần ta chỉ đề cập đến cách ghi chú trong Java chứa không phải là cách ghi chú cho tất cả.

2.1. Ghi chú trên một dòng

Cách ghi chú này thường dùng để giải thích một dòng lệnh trong Java. Và chú thích này cũng rất là ngắn. Cụ thể là chú thích nên dưới 120 ký tự. Vì theo lời khuyên các tiêu chuẩn về Code Convention thì một dòng code không nên quá 120 ký tự. Nhưng nếu ta viết ghi chú dài hơn thì vẫn không phải là lỗi. Miễn sau nó nằm trên 1 dòng thôi. Nó được bắt đầu bằng // và kết thúc là xuống dòng.

// Set value for `name` variable
String name = "Tien Nguyen";

Ta cũng có thể sử dụng ghi chú trên một dòng như thế này. Bắt đầu /* và kết thúc */.

/* Set value for `name` variable */

Ta cũng có thể ghi chú lớn hơn 1 dòng bằng cách dùng // mỗi đầu dòng thôi.

// Set value for `name` variable
// Value of name is String type.

Nhưng Java khuyên ta dùng cách ghi chú trên dòng theo cách khác.

2.2. Ghi chú trên nhiều dòng

Java hỗ trợ ta ghi chú trên nhiều dòng bằng cách sử dụng /** … */. Trong … là những dòng ghi chú. Cụ thể là dòng ghi chú trên được chuyển thành:

/**
 * Set value for `name` variable
 * Value of name is String type.
 */

Không gì phải lo lắng khi mà cách viết này điều được các trình soạn thảo Java hỗ trợ. Ta chỉ cần gõ /** và nhấn phím Enter thì trình soạn thảo sẽ tự động thêm các ký tự còn lại. Ta chỉ cần viết nội dung vào đó thôi.

3. Ghi chú được sử dụng ở đâu?

Lập trình viên thường thêm ghi chú của mình trong thân của một phương thức, đầu của một phương thức hay bên cạnh các thuộc tính của một lớpđầu các lớp để mô tả những gì khối mã đó sẽ làm.

/**
 * Add sub name to name.
 * @param name: name of person
 * @return name after add sub name.
 */
 public String changeName(String name) {
    // add sub fix of name
    name.concat(", Ng");
    return name;
}

Đoạn mã trên minh họa cách ghi chú trong thânđầu của phương thức.

/**
 * <h1>Student in University</h1>
 * Description Student class in here.
 * Please see more {@link MainComment}
 * <p>
 * Use when need write comment in many line.
 * Format of Editor will not change it.
 * </p>
 *
 * @author Tien Nguyen
 * @version 1.0
 * @since 2019-04-10
 */
public class Student {

    // name of student
    private String name;
    // age of student
    private int age;
    // address that student temporary residence.
    private String address;
    //...
}

Đoạn mã trên minh họa ghi chú ở đầu của lớp và các thuộc tính của lớp đó. Ta thấy trong đây có thể sử dụng cả các tag của HTML để nhầm hiện thị nó tốt hơn trong các trình soạn thảo.

Trong đây có vài từ mới như @author, @version, @param, @return… đây là các annotation được thêm vào theo tiêu chuẩn của JavaDoc. JavaDoc sẽ căn cứ vào chúng để sinh ra tài liệu hướng dẫn dưới định dạng HTML. Ta sẽ được tìm hiểu chi tiết ở Tìm hiểu sơ lược Javadoc.

Các ghi chú cũng hữu dụng trong các trình soạn thảo Java. Khi ta có ghi chú của một phương thức tốt. Thì trình soạn thảo sẽ giúp ta thấy được nó thông qua các hộp thoại của nó.

Hình 1 0 Hộp thoại mô tả chức năng của phương thức “changeName” bằng IntelliJ.

Trong Hình 1 ta thấy được công dụng của ghi chú trong các trình soạn thảo của Java. JavaDoc cũng sử dụng các ghi chú này để sinh ra các HTML để làm tài liệu hướng dẫn sử dụng cho các Lập trình viên.

4. Tìm hiểu sơ lược JavaDoc

Javadoc là một công cụ đến từ JDK. Nó có nhiệm vụ sinh ra các thông tin của một phương thức hay một lớp của Java dưới định dạng HTML dựa trên các ghi chú từ một lớp và ghi chú của một phương thức.

Bảng 1 – Các thẻ (tags) trong JavaDoc

Thẻ Mô tả Cứu pháp
@author Tác giả tạo
nên lớp. Thường thì các trình soạn thảo lấy tên của máy tính để điền vào nếu
ta không chủ động khai báo từ các tham số của trình soạn thảo.
@author [name of
author]
@deprecated Cảnh báo cho người dùng tính năng sẽ không được sử dụng
trong phiên bản sau.
@deprecated it was removed in next versions
@exception Khai báo các ngoại
lệ
có thể xảy ra khi sử dụng tính năng này.
@exception Exception Class
@throw Khái báo các ngoại
lệ
có khả năng được bắn ra.
@throw class_name description
@param Tên biến và mô tả công dụng của biến đo trong chương
trình. Biến này là tham số của phương thức.
@param variable_name: description
@return Mô tả những gì sẽ được trả về sau khi thực hiện phương
thức.
@return description
@see Mô tả đường dẫn hay là văn bản để tham khảo thêm. @see reference
@version Khai báo phiên bản của ứng dụng. Nó là một văn phản có
định dạng số.
@sine 1.0.0
@serial
@serialData
@serialField
Sử dụng trong các trường hợp cần serialize dữ liệu. @serial field_description | include |  exclude
 
@serialData data_description
 
@serialField field_name field_type
field_description
{@code} Hiển thị chữ
dưới định dạng mã nguồn chứ không hiển thị theo định dạng của HTML như bình
thường
{@code text}
{@docRoot} Đường dẫn thư tương đối gốc của tài liệu. {@docRoot}
{@inheritDoc} Kế thừa tài liệu từ lớp cha của nó. {@inheritDoc}
{@link}
{@linkplain}
Thêm một liên kết để bỗ sung thêm ý muốn mô tả trong
ghi chú.
@link
thì hiển thị liên kết @linkplain
thì hiển thị văn bản.
{@link package_name.class#method label}
{@value} Sử dụng khi muốn hiển thị giá trị của constant. {@value package.class#field}

Trên là các từ khóa được dùng để ghi chú trong JavaDoc. Nhưng ta không cần phải ghi nhớ nhiều vì trong các trình soạn thảo hỗ trợ Java đã tự động thêm vào khi ta muốn thêm ghi chú. Ta chỉ cần hiểu nó sử dụng cho mục đích gì và khi nào dùng nó thôi.

5. JavaDoc trong Trình soạn thảo

JavaDocs được các trình soạn thảo hỗ trợ sinh ra dưới dạng HTML để làm tài hiệu hướng dẫn cách sử dụng các phương thức trong gói mã mà ta đang viết.

Hình 2 - HTML được sinh ra từ JavaDoc

5.1. JavaDoc trong IntelliJ

Trình soạn thảo Java cũng hỗ trợ quá trình sinh ra JavaDoc. Trong IntelliJ để sinh JavaDoc cho dự án hiện tại (đang được mở).

  1. Chọn Tool -> Generate JavaDocs. Hộp thoại Specify Generate JavaDoc Scope xuất hiện.
  2. Ta cần chỉ ra đường dẫn chứa các tập tin HTML mà ta cần sinh ra ở Output Directory.
  3. Click OK.

Sau khi OK được click thì JavaDoc sinh ra các tập tin HTML với trang có định dạng như trong hình (Hình 2).

5.2. JavaDoc trong Netbean

Trong Netbean thì cũng đơn giản như là trong IntelliJ. Chỉ cần chọn dự án muốn sinh JavaDoc sau đó chọn Generate JavaDoc là Netbean làm tất cả. Các tập tin HTML sẽ được chứa trong thư mục dist cùng thư mục của dự án (Hình 2).

5.3. JavaDoc trong CMD

Nếu ta không sử dụng các trình soạn thảo trên để sinh ra các tập tin HTML thì ta cũng có thể dùng câu lệnh trong DOS (CMD – Command Line DOS) để làm điều này. Thực ra các trình soạn thảo không tự viết chức năng của JavaDoc mà họ cũng sử dụng dòng lệnh để sinh ra thôi. Nó đã được hỗ trợ từ JDK của Java.

Hình 3 - Cấu trúc thư mục sinh ra sau khi chạy "Generate JavaDoc" trong Netbean.

Để sử dụng được dòng lệnh ta cần đảm bảo JavaDoc đã được khai báo trong các biến môi trường của Java. Ta có thể kiểm tra nó bằng cách.

  1. Nhấn phím Window. Gõ cmd để mở Command Prompt.
  2. Đọc nội dung hiển thị sẽ biết nó có đang được hỗ trợ hay không.
  3. Nếu không, ta cần khi báo biến môi trường. Vào Computure ð Property ð Advanced System Setting (phía bên trái màn hình). Hộp thoại System Property hiện lên. Sau đó tìm tab Advanced và click nút Environment
    Variables
    … để thiết lập.
  4. Hộp thoại Evironment Variables hiện lên. Trong phần User variable for … chọn Path. Thêm đường dẫn của JDK vào là sẽ OK. Thường mặc định đường dẫn của Java là C:\Program Files\Java\jdk1.8.0_181\bin trong Window 10.

Quay lại gõ javadoc sẽ thấy được các dòng hướng dẫn sử dụng của nó. Đọc lướt qua các hướng dẫn của nó là ta làm được ngay. Trong đây tôi xin đề cập một dòng lệnh cơ bản nhất để sinh ra JavaDoc trong một gói (package).

javadoc –sourcepath {path_of_java_project} –d {path_html_result} \n
    –subpackages {package.name.of.project}

Khi chạy dòng lệnh trên ta sẽ vào trong {path_html_of_result} để xem kết quả của HTML trả về. Khi mở tập tin index.html thì cũng sẽ giống Hình 2.

Trong phần này tôi xin không đi sâu vào JavaDoc vì tôi sẽ có một bài viết khác để thấy được tầm quan trọng của nó trong lập trình.

6. Quan điểm không Ghi chú

Mã Java để máy tính hiểu thông qua trình biên dịch của Java. Còn ghi chú là để các lập trình viên hiểu. Do đó nó khá quan trọng trong làm việc nhóm và bảo trì. Trong các công ty phần mềm lớn điều có tham vọng bắt Lập trình viên điều phải viết ghi chú trong quá trình viết mã.

Viết ghi chú đầy đủ thì rất tốn nhiều thời gian. Do đó có thêm một quan điểm mới là không cần viết ghi chú. Nhưng bù lại phải xây dựng cấu
trúc dể hiểu
đặt tên các phương thức sau cho nó có nghĩa như là một ngôn ngữ ngữ tự nhiên. Điều này nghe qua thì dể nhưng đó là một thách thức.

Bên cạnh đặt tên các phương thức dể hiểu thì ta cần phải thực hiện các dòng chảy (flow) dữ liệu có thể giúp ta có thể liên tưởng đến đời sống thực hàng ngày.

Ví dụ khi ta đang làm ứng dụng liên quan đến truyền tải dữ liệu, đặt tên các phương thức để xử lý luồng dữ liệu ta có thể ánh xạ nó vào quy trình giao nhận hàng quá ngoài thực tế. Lúc đó dữ liệu là hàng hóa.

Các đối tượng xử lý là nhân viên chuyển hàng hay các trạm trung chuyển… Điều này tốt nhưng hãy cẩn thận, nếu ta ánh xạ không đúng vào một lĩnh vực được nhiều người hiểu thì đây được xem là thảm họa trong tương lai.

Theo tôi thì cách này hay nhưng đầy thách thức. Nếu ta làm được
điều này thì ta có thể đoán được cơ chế hoạt động bên trong mà không cần đọc
thêm nhiều tài liệu chuyên sâu về nó. Vì ta đã tiếp xúc với các bước làm này
trong thực tế rồi đúng không?

7. Tóm lược

Ghi chú sẽ rất tốt cho Lập trình viên. Nó giúp lập trình viên tiết kiệm nhiều thời gian trong quá trình viết mã. Nó cũng giúp chính tác giả của đoạn mã đó nâng cao hiệu suất làm việc khi bảo trì sản phẩm. Đối với dòng (flow) phức tạp, nếu có ghi chú sẽ giảm đi độ phức tạp của nó lên gấp nhiều lần.

Ghi chú có tác dụng để giao tiếp các lập trình viên với nhau. Nhưng nếu tên phương thức, dòng (flow) đơn giản thì ta cần ghi chú không? Nếu ta làm thế là dư thừa vì bản thân tên hàm đã nói lên tính năng đó. Một giải pháp hay để giảm thiểu chi phí cho ghi chú là đặt tên phương thức, biến, lớp tường minhánh xạ dòng (flow) vào cuộc sống thực ngoài đời. Giải pháp này giúp
thiết kế bền vững hơn.

Ngoài sử dụng trình soạn thảo để xem ghi chú của các hàm, biến, lớp… thì ta có thể sử dụng HTML để xem nó. JavaDoc hỗ trợ ta điều này. Nó sinh ra các HTML dựa trên tiêu chuẩn ghi chú của JavaDoc. Các ghi chú này được JavaDoc đọc rồi biên dịch thành HTML. HTML có thể được sử dụng để gửi đi hoặc công bố trên một máy chủ để nhiều Lập trình viên có thể xem được.

Tóm lại nếu sử dụng Java ghi chú đúng mục đích sẽ tiết kiệm nhiều thời giancông sức cho Lập trình viên. Nó giúp các ứng dụng giảm đi lỗi khi những dòng mã được viết dựa trên sự tin tưởng tuyệt đối về cung dụng của cái mà họ đang sử dụng.

Hi vọng bài viết giúp ta có cái nhìn thân thiện hơn với ghi chú trong quá trình viết mã. Tôi sẽ cố gắng truyền tải những quan điểm dựa trên kinh nghiệm cá nhân để giúp các bạn mới bắt đầu có cái nhìn khác về những gì bạn đã học.

Bạn có thể tham khảo mã nguồn ở https://github.com/tiennguyen2009/java-basic/tree/master/src/com/tiennguyen/chapter_2/comment

Tài liệu tham khảo

  1. Tourial Points. Java – Documents Comment. https://www.tutorialspoint.com/java/java_documentation.htm

  2. Câu lạc bộ tin học – ĐH Đồng Nai. Cách tạo ghi chú trong Java. http://clbtinhoc.dntu.edu.vn/index.php/bai-7-cach-tao-ghi-chu-trong-java/

Trả lời

Email của bạn sẽ không được hiển thị công khai. Các trường bắt buộc được đánh dấu *