Viết tài liệu cho các phương thức được hiểu rõ như bằng trong Java

Có phải là một thực hành tốt để viết bình luận cho các phương pháp được biết đến rộng rãi như bằng, so sánh vv?

Hãy xem xét mã dưới đây.

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

Công ty của tôi tức giận nhập các bình luận như trên. Có phải bình luận Javadoc ở trên không? Có phải nó không rõ ràng và được hiểu rõ những gì phương thức bằng và thích (so sánh, so sánh) vv không?

Đề xuất của bạn là gì?

JavaDoc đã hỗ trợ kế thừa các bình luận . Theo tài liệu này, "các hàm tạo, các trường và các lớp lồng nhau không kế thừa các nhận xét doc", nhưng các phương thức như là equals()ý chí. Vì Objectlớp có một equals()phương thức được làm tài liệu tốt , bạn sẽ có thể kế thừa tài liệu đó mà không gặp vấn đề gì.

Tài liệu cho phương thức cần đến từ một nơi nào đó để có thể truy cập được trong IDE của bạn và trong tài liệu web được tạo. Hoàn toàn viết lại các bình luận chính xác và toàn diện tồn tại trong một siêu lớp là không cần thiết, và tôi sẽ tranh luận về việc làm xáo trộn các tệp mã.

Nếu đây là chính sách của công ty, thì bạn có hai lựa chọn. Bạn có thể đi cùng với nó một cách nhẹ nhàng và xử lý thêm nỗ lực viết và duy trì tài liệu (thường vi phạm nguyên tắc DRY, cũng có thể được áp dụng cho các tài liệu cũng như mã). Tùy chọn khác là tìm kiếm chính sách của công ty - giải thích lý do tại sao chính sách này không phải là ý tưởng hay và lợi ích của việc thay đổi nó (về thời gian, tiền bạc, công sức, chất lượng - những điều mà quản lý hiểu).

Trong nhóm của tôi, chúng tôi thường sử dụng @inheritDocchú thích cho equals()và hashcode()nhưng tôi ước chúng tôi đã không làm vậy.

Đối với hai phương pháp này tôi luôn phải xem xét việc thực hiện. Vì bạn đang ghi đè một phương thức, điều đó có nghĩa là bạn muốn nó làm một cái gì đó khác biệt. Tôi nghĩ rằng điều này xứng đáng tài liệu riêng của mình.

Ít nhất là tốt để ghi lại những thuộc tính nào tham gia vào phương thức và thậm chí có thể tại sao lại như vậy.

Hãy nhớ rằng các bình luận giúp các nhà phát triển của tất cả các loại nếu chúng là chính xác.

Vấn đề là đôi khi chúng không đầy đủ và không chính xác.

Thành thật mà nói, so sánh 2 đối tượng có thể khó khăn (ví dụ so sánh 2 đối tượng hóa đơn), phương pháp của bạn có thể phát triển theo thời gian và sau đó sẽ cần phải được nhận xét.

Hiển thị mục tiêu phương pháp, quy tắc, vv trong một nhận xét "hữu ích và có ý nghĩa" là một điều tốt.

Việc xả rác mã với các bình luận trống rỗng như:

/**
 * This method compares the equality of the current object with the object of same type...
 */

Điều này nói không có gì hữu ích. Tệ hơn, nó kém cả về phong cách và ngữ pháp:

1. Nhận xét không bao giờ nên bắt đầu bằng "Phương pháp này" hoặc "Lớp này" hoặc "Điều này" bất cứ điều gì. Nhận xét được liên kết với một phương thức hoặc lớp theo vị trí của nó trong tệp nguồn.

2. "đối tượng" nên đọc "một đối tượng"

3. "So sánh sự bình đẳng" chỉ có ý nghĩa nếu một đối tượng có thể có nhiều "bình đẳng" hơn đối tượng khác. Hàm này không so sánh "đẳng thức"; nó so sánh các đối tượng để xác định sự bình đẳng của chúng với nhau.

Thay vào đó, bình luận nên chỉ ra khi hai đối tượng được coi là bằng nhau. Ở đây, tôi sẽ bỏ qua mô tả phương thức hoàn toàn và chỉ ghi lại giá trị trả về, ví dụ:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

Nhận xét được tạo cho các phương thức get / set tầm thường là tồi tệ nhất trong tất cả.

Tiêu chuẩn mã hóa của chúng tôi chỉ ra rằng khi ghi đè một phương thức, không cần thiết phải ghi lại nó trừ khi, khi ghi đè lên nó, tài liệu trong lớp cha hoặc giao diện không còn chính xác và toàn diện cho lớp phụ hoặc lớp triển khai.

Đối với bằng, chúng tôi có thể muốn lưu ý rằng việc so sánh chỉ được thực hiện trên khóa chính khi so sánh một thực thể được hỗ trợ cơ sở dữ liệu vì điều đó không hoàn toàn phù hợp với tài liệu cho Object.equals().

Theo tôi, và tôi nghĩ điều này có thể gây tranh cãi, bạn nên nêu trong nhận xét về lớp nào bạn đã ghi đè lên lớp. Sau đó sáu tháng, khi bạn tự hỏi liệu nó có được thực hiện hay không, bạn sẽ có thể nhìn thấy mà không cần mở lớp.

Biết rằng các phương thức đó là phổ biến và hầu hết các nhà phát triển sẽ biết họ đang làm gì sau đó, IMO, bạn sẽ không cần phải đưa bất kỳ bình luận nào vào đó. Nhận xét không đáng tin cậy trong thời gian dài vì có nhiều khả năng những điều này có thể không được cập nhật khi triển khai được cập nhật và có thể gây nhầm lẫn. Vì vậy, sẽ luôn tốt hơn để làm cho mã của bạn có thể đọc được vì đây là điều bạn có thể tin tưởng nhất.

Hơn nữa, tôi sẽ nói rằng nếu mã bạn đang tạo / chỉnh sửa không dành cho API công khai thì hãy bỏ qua javadocs cho các phương thức phổ biến vì chúng sẽ chỉ gây thêm lộn xộn và nhiễu.