Bình luận Java

Chú thích là một phần của chương trình không được thực thi. Trình biên dịch đơn giản bỏ qua các nhận xét vì chúng không dành cho nó. Chúng được viết bằng ngôn ngữ “con người” và nhằm mục đích giải thích chương trình, một phần của chương trình, một dòng hoặc phương pháp duy nhất cho các nhà phát triển hoặc những người tham gia vào quá trình phát triển. Thông thường, các bình luận được viết bằng tiếng Anh, đó là một truyền thống. Trong bài viết này, chúng ta sẽ nói về các nhận xét trong Java và cách sử dụng chúng một cách chính xác để giúp bạn và đồng đội của bạn dễ dàng hơn.

Nhận xét Java: tại sao chúng quan trọng

Họ nói rằng các lập trình viên cực kỳ lười biếng khi bình luận về mã của chính họ. Tuy nhiên, đây là một kỹ năng rất quan trọng nên đừng đánh giá thấp nó, ngay cả khi bạn mới bắt đầu học Java. Mã được chú thích tốt có giá trị hơn nhiều so với mã không có chú thích vì chương trình như vậy dễ bảo trì hơn nhiều. Vì các dự án lớn thường được viết bằng Java, nên việc bình luận có thẩm quyền cũng giúp tăng tốc độ phát triển, vì lập trình viên sẽ dễ dàng xử lý mã của người khác hơn. Bình luận là cần thiết để:

Hiểu mã. Của bạn hoặc của người khác. Nếu đối với bạn, có vẻ như bạn không cần phải giải mã mã của chính mình vì bạn đã viết nó, hãy thử mở một chương trình tương đối phức tạp mà bạn đã viết cách đây một tháng hoặc thậm chí sớm hơn và nhanh chóng hiểu bạn nghĩ gì, ở đâu và tại sao. Nhận xét có thể được sử dụng để giải thích logic của chương trình hoặc khối chương trình, cũng như để lại đề xuất cho những người sẽ làm việc với mã của bạn sau này. Loại bình luận này có thể được gọi là giải thích.
Chứa thông tin về mục đích của đối tượng, các tham số đầu vào và đầu ra (nếu có), dữ liệu về nhà phát triển và những thứ quan trọng khác liên quan đến đoạn mã. Những nhận xét như vậy nằm trong tiêu đề của mô-đun, thư viện, thủ tục và hàm. Chúng có thể được gọi là nhận xét tài liệu.
Kiểm soát lỗi và cải thiện mã. Mã có vấn đề hoặc mã cần cải thiện luôn có thể được nhận xét và xem lại sau. Nếu bạn chợt nhận ra rằng một vấn đề nào đó có thể được giải quyết theo một cách khác, nhưng bây giờ bạn không có thời gian cho việc đó, hãy viết ý tưởng này vào phần bình luận. Nếu không, rất có thể, dưới áp lực của mã mới, bạn sẽ quên nó.

Các loại bình luận trong Java

Mặc dù thực tế là bạn có thể viết bất kỳ thứ gì và mọi thứ trong nhận xét, nhưng có một số loại nhận xét nhất định trong Java và các quy tắc sử dụng chúng. Trong các bình luận Java có thể là:

Nhận xét một dòng
Bình luận nhiều dòng
Nhận xét tài liệu

Nhận xét một dòng

Các chú thích Java phổ biến nhất là các chú thích một dòng. Để biểu thị nhận xét như vậy, chỉ cần đặt dấu gạch chéo kép trước văn bản // là đủ . Nhận xét một dòng chỉ được gắn cờ ở đầu nhận xét. Bình luận tiếp tục đến cuối dòng. Cú pháp:

//here is a single line comment.

Hãy lấy một ví dụ về loại nhận xét Java này:

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

Đầu ra là:

Văn bản này hiển thị cho trình biên dịch Java

Thông thường, chú thích một dòng nằm ở trên hoặc dưới vị trí được chú thích trong chương trình, đôi khi trên cùng một dòng. Điều quan trọng là phải thể hiện rõ ràng nội dung nhận xét đề cập đến.

Bình luận nhiều dòng

Đôi khi không đủ một dòng để viết bình luận Java. Ví dụ: bạn cần mô tả cách hoạt động của một phương pháp hoặc một công thức phức tạp mà bạn đang triển khai. Trong trường hợp này, bạn có thể viết nhiều bình luận một dòng, nhưng sẽ hợp lý hơn nếu viết cái gọi là bình luận nhiều dòng. Chúng được đánh dấu trên cả hai mặt bằng ký hiệu /* */ . Cú pháp comment nhiều dòng:

/*This comment
is
Multi line comment
we can describe here
what we need */

Hãy lấy một ví dụ về nhận xét nhiều dòng trong mã

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

Nhận xét tài liệu Java

Đây là một loại nhận xét Java đặc biệt được sử dụng để tạo trang tài liệu. Thông thường, các nhà phát triển viết nhận xét tài liệu bằng cách sử dụng Javadoc, một trình tạo tài liệu để tạo tài liệu API ở định dạng HTML từ mã nguồn Java. Định dạng tài liệu được Javadoc sử dụng là tiêu chuẩn công nghiệp để ghi lại các lớp Java và các IDE phổ biến nhất như IntelliJ IDEA và Eclipse, tự động tạo HTML Javadoc. Nhận xét tài liệu Java có cú pháp dưới đây:

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

Đây là một ví dụ: đó là một đoạn của lớp Java Short . Nhân tiện, bạn có thể xem bất kỳ mã lớp Java nào từ IDE của mình (ví dụ: trong IntelliJ IDEA từ Windows, chỉ cần nhấn ctrl+LBM hoặc ctrl + b (trong Windows) trên bất kỳ tên lớp hoặc phương thức nào).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

Đây là mã Java của phương thức println() nổi tiếng và được yêu thích bởi tất cả người mới sử dụng với nhận xét như sau:

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

Javadoc có một số thẻ Javadoc đặc biệt được đánh dấu bằng @ bạn có thể thấy trong đoạn mã trên. Ví dụ về thẻ Javadoc như vậy là @author để thêm tên của tác giả lớp. Một thẻ Javadoc khác là @since nó thêm một nhận xét cho biết rằng lớp này được sử dụng kể từ phiên bản Java được chỉ định. Viết tài liệu Javadoc tốt đòi hỏi kiến thức và kinh nghiệm (và sự kiên nhẫn!). Bạn có thể tìm thêm thông tin về Javadoc trong tài liệu chính thức Cách viết nhận xét tài liệu cho Công cụ Javadoc .

PS một số ví dụ bình luận hài hước từ cuộc sống thực

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

Để củng cố những gì bạn đã học, chúng tôi khuyên bạn nên xem bài học video từ Khóa học Java của chúng tôi