Nhận xét trong Java: không phải mọi thứ đều đơn giản như vậy

Giới thiệu

Nhận xét - có vẻ như nó có thể đơn giản hơn và tại sao phải viết cả một bài báo. Nhưng nó không đơn giản như vậy. Như sếp tôi đã nói, ai cũng có thể viết code nhưng viết được một bình luận hay thì khó. Hầu hết các khóa học ngôn ngữ đều bắt đầu với Hello World truyền thống. Ngay cả trong Hướng dẫn của Oracle, trong phần "Bắt đầu", chúng tôi bắt đầu bằng "Xin chào thế giới!" Ứng dụng . Và ngay từ những dòng mã đầu tiên, chúng ta đã thấy chúng - các bình luận Java. Tầm quan trọng của chúng cũng được nhấn mạnh bởi thực tế là trong một tài liệu quan trọng như Công ước Mã Java, các nhận xét được đưa ra một phần riêng: Nhận xét . Theo tài liệu, các bình luận trong Java được chia thành hai loại:

• nhận xét thực hiện (hoặc nhận xét mã);
• ghi lại nhận xét.

Nhận xét mã được sử dụng để mô tả các dòng/khối riêng lẻ và nhận xét tài liệu được sử dụng để mô tả đặc tả mã (giao diện của nó) độc lập với việc triển khai mã. Các chú thích Java bị trình biên dịch bỏ qua vì chúng có ý nghĩa đối với nhà phát triển chứ không phải với người dùng. Vì vậy, bạn có thể giảm kích thước của các lớp được biên dịch.

Nhận xét mã Java

Ngay từ cái tên, rõ ràng nhận xét này liên quan đến mã và sẽ phản ánh các tính năng của nó. Nhận xét mã là:

• Chữ thường (tức là được mô tả trong một dòng)

  // Строчный комментарий
  System.out.println("Hello, World!");




• Khối (tức là chúng được mô tả dưới dạng toàn bộ khối, vì chúng không vừa trên một dòng)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Một tính năng thú vị của nhận xét khối là nếu chúng ta bắt đầu nó bằng “ /*- ” (tức là thêm dấu trừ sau dấu hoa thị), thì văn bản của nhận xét khối này sẽ không được định dạng. Thật thú vị, nhưng với sự trợ giúp của một số nhận xét nhất định, bạn có thể đưa ra một số gợi ý về IDE. Ví dụ: bằng cách sử dụng các nhận xét nội tuyến " //@formatter:on " và " //@formatter:off " trong IDE Eclipse, bạn có thể tắt định dạng cho các phần mã. Bạn cần sử dụng bình luận một cách tiết kiệm và chỉ khi cần thiết. Ví dụ: bạn có thể đọc một bài viết về chủ đề này: “Đừng viết bình luận về mã!” . Có một cuốn sách hay tên là Clean Code: Create, Analysis, and Refactoring của Robert Martin. Nó có một chương riêng “Bình luận”. Như một lời đề tặng cho chương này, một câu trích dẫn xuất sắc không kém: “Đừng bình luận về mã xấu - hãy viết lại nó” từ Brian W. Kernighan và P. J. Plover. Chương này có thể được tìm thấy trên Google Sách . Ý nghĩa chung có thể được thể hiện trong một trích dẫn của ông:

Mỗi lần bạn bình luận, hãy nhăn mặt và cảm thấy mình thất bại."

Rõ ràng là không có sự thật tuyệt đối và đôi khi cần có những bình luận. Nhưng luôn có những lựa chọn và những bình luận không cần thiết cần phải được đấu tranh. Chương này cũng đề cập đến những bình luận bất thường, TODO:

// TODO: Добавить World
System.out.println("Hello, ");

Mục đích của chúng là chúng có thể được xử lý theo cách đặc biệt trong IDE. Ví dụ: trong IDEA chúng được thu thập trên một tab riêng biệt, nơi bạn có thể xem chúng: Và một người giải đố nhỏ có nhận xét: Dòng “http://google.com” là một dòng hợp lệ bên trong phương thức, bởi vì http ở đây thực chất là một thẻ và sau đó là một nhận xét. Thông thường, nhiều nhận xét có thể đi từ nhận xét mã đến nhận xét tài liệu, điều mà chúng ta sẽ nói đến sau.

Bình luận cho tài liệu

Nhận xét tài liệu mô tả API công khai. API là giao diện lập trình ứng dụng, nghĩa là các lớp và phương thức có sẵn cho các nhà phát triển khác để thực hiện bất kỳ hành động nào. Nói tóm lại, những nhận xét này sẽ giải thích lý do tại sao lớp và gói đó được tạo ra và phương thức này hoặc phương thức đó làm gì. Bạn cũng có thể mô tả các trường lớp nếu cần. Đây chính xác là những gì chúng ta thấy trong chú giải công cụ của IDE, được định dạng dưới dạng JavaDoc. Ví dụ: Nếu chúng ta đi sâu vào phương pháp này, chúng ta có thể thấy văn bản này đến từ đâu: Một lần nữa, hãy xem Quy ước mã Java: Quy ước mã về cách định dạng đúng JavaDoc . Chúng hơi giống với khối bình luận, nhưng thay vì một dấu hoa thị (không phải dấu hoa thị)), hai dấu hoa thị được sử dụng. Một ví dụ JavaDoc đã được đưa ra ở trên. Không có ích gì khi mô tả tất cả các khả năng, vì điều này đã được viết trong tài liệu chính thức của Oracle. Do đó, chúng tôi xem xét mọi thứ chúng tôi cần trong tài liệu JavaDoc chính thức , phần "Mô tả thẻ". Oracle thậm chí còn có một hướng dẫn riêng về chủ đề này: How to Write Doc Comments for the Javadoc Tool . Các chú giải công cụ trong IDE rất hay, nhưng chúng thực sự là tài liệu vì một lý do. Dựa trên những nhận xét JavaDoc này, tài liệu sẽ được tạo ra. Có một tiện ích javadoc đặc biệt cho việc này . Như chúng ta có thể thấy, Hướng dẫn đó nói về điều này. Mô tả về cách sử dụng nó có trên trang web chính thức của Oracle dành cho JavaDoc . Để tự mình xem nó trông như thế nào, bạn có thể tạo một thư mục con trong thư mục có tên của gói, ví dụ: test . Tạo một lớp đơn giản với các bình luận trong đó. Ví dụ:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

Sau này, chúng ta có thể chạy lệnh sau từ thư mục chứa thư mục gói của chúng ta: javadoc -d ./test test Sau này, chúng ta sẽ thấy quá trình tạo tài liệu. Và sau đó chúng ta có thể mở index.html để xem tài liệu được tạo. Bạn sẽ thường thấy tài liệu API được đăng. Ví dụ: API Spring Framework .

Phần kết luận

Như chúng ta có thể thấy, một điều tưởng chừng đơn giản như nhận xét hóa ra lại phức tạp hơn nhiều trong thực tế. Do đó, nếu bạn dành chút thời gian cho các bình luận và theo dõi chúng, mã của bạn sẽ tốt hơn và bạn sẽ có giá trị hơn với tư cách là một lập trình viên. #Viacheslav