Làm thế nào để viết Javadoc của thuộc tính?

Tôi thường thấy mình gặp tình huống khó xử khi viết javadoc cho các thuộc tính / thành viên của một lớp POJO "đơn giản" chỉ chứa các thuộc tính và getters và setters (kiểu DTO) ....

1) Viết javadoc cho thuộc tính
hoặc ...
2) Viết javadoc cho getter

Nếu tôi viết javadoc cho thuộc tính, IDE (Eclipse) của tôi (đương nhiên) sẽ không thể hiển thị điều này khi tôi truy cập POJO sau đó thông qua hoàn thành mã. Và không có thẻ javadoc chuẩn nào cho phép tôi liên kết getter-javadoc với thuộc tính thực tế javadoc.

Một ví dụ:

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }  

Vì vậy, về cơ bản sẽ rất thú vị khi nghe những người khác làm thế nào để IDE Eclipse của bạn hiển thị mô tả thuộc tính javadoc cho getters của bạn - mà không cần phải sao chép nhận xét javadoc.

Hiện tại, tôi đang xem xét việc thực hành của mình để chỉ ghi lại các getters chứ không phải các thuộc tính. Nhưng nó có vẻ không phải là giải pháp tốt nhất ...

Bạn có thể bao gồm các thành viên riêng tư trong khi tạo Javadocs (sử dụng -private) và sau đó sử dụng @link để liên kết đến thuộc tính trường đó.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

Ngoài ra, nếu bạn không muốn tạo Javadoc cho tất cả các thành viên riêng tư, bạn có thể có một quy ước để ghi lại tất cả các getters và sử dụng @link trên các setters.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}

Lombok là một thư viện rất thuận tiện cho những công việc như vậy.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

Đó là tất cả những gì cậu cần! Các@Getter chú thích tạo ra một phương thức getter cho mỗi lĩnh vực tư nhân và đính kèm các javadoc với nó.

Tái bút : Thư viện có nhiều tính năng thú vị mà bạn có thể muốn kiểm tra

Tôi làm cả hai, được hỗ trợ bởi tính năng tự động hoàn thành của Eclipse.

Đầu tiên, tôi ghi lại tài sản:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Sau đó, tôi sao chép và dán nó vào getter:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Với eclipse, các câu lệnh @return có tính năng tự động hoàn thành - vì vậy, tôi thêm từ Gets, viết thường chữ "t" và sao chép câu với chữ "t" viết thường. Sau đó, tôi sử dụng @return (với tính năng tự động hoàn thành của Eclipse), dán câu và sau đó viết hoa chữ T trong câu trả lời. Sau đó nó trông như thế này:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Cuối cùng, tôi sao chép tài liệu đó sang người thiết lập:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Sau đó, tôi sửa đổi nó và với tính năng tự động hoàn thành Eclipse, bạn không chỉ có thể nhận được thẻ @param mà còn có tên của tham số:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Sau đó, tôi đã hoàn thành. Theo ý kiến ​​của tôi, việc tạo khuôn mẫu này giúp bạn dễ dàng hơn rất nhiều, về lâu dài, không chỉ nhắc nhở bản thân về ý nghĩa của thuộc tính thông qua việc lặp lại mà còn giúp bạn dễ dàng thêm các nhận xét bổ sung vào getter và setter nếu bạn muốn thêm bên. hiệu ứng (chẳng hạn như không cho phép thuộc tính null, chuyển chuỗi thành chữ hoa, v.v.). Tôi đã điều tra tạo một plugin Eclipse cho mục đích này nhưng tôi không thể tìm thấy điểm mở rộng thích hợp cho JDT, vì vậy tôi đã từ bỏ.

Lưu ý rằng câu có thể không phải lúc nào cũng bắt đầu bằng chữ T - nó chỉ là chữ cái đầu tiên phải được viết hoa / viết hoa lại khi dán.

Tôi thực sự nghĩ rằng đó là một vấn đề và hướng dẫn Javadoc chính thức không cho biết bất cứ điều gì về nó. C # có thể giải quyết điều này một cách thanh lịch với cách sử dụng Thuộc tính (Tôi không viết mã bằng C #, nhưng tôi thực sự nghĩ rằng đó là một tính năng hay).

Nhưng tôi có một phỏng đoán: nếu bạn cần giải thích someString là gì, có thể đó là một `` điều tồi tệ '' về mã của bạn. Nó có thể có nghĩa là bạn nên viết SomeClass để nhập someString, vì vậy bạn sẽ giải thích someString là gì trong tài liệu SomeClass và chỉ vì vậy javadocs trong getter / setter sẽ không cần thiết.