วิธีการเขียนคุณสมบัติ Javadoc

ฉันมักจะพบว่าตัวเองกลืนไม่เข้าคายไม่ออกเมื่อเขียน javadoc สำหรับคุณสมบัติ / สมาชิกของคลาส POJO แบบ "ธรรมดา" ที่มี แต่คุณสมบัติและตัวรับและตัวตั้งค่า (แบบ DTO) ....

1) เขียน javadoc สำหรับคุณสมบัติ
หรือ ...
2) เขียน javadoc สำหรับ getter

ถ้าฉันเขียน javadoc สำหรับคุณสมบัติ IDE (Eclipse) ของฉันจะ (ตามธรรมชาติ) ไม่สามารถแสดงสิ่งนี้ได้เมื่อฉันเข้าถึง POJO ในภายหลังผ่านการเติมโค้ด และไม่มีแท็ก javadoc มาตรฐานที่ให้ฉันเชื่อมโยง getter-javadoc กับคุณสมบัติที่แท้จริงของ javadoc

ตัวอย่าง:

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;  
  }  

ดังนั้นโดยพื้นฐานแล้วมันเป็นเรื่องที่น่าสนใจที่จะได้ยินว่าคนอื่นคิดอย่างไรกับการมี Eclipse IDE ของคุณแสดงคำอธิบายคุณสมบัติ javadoc สำหรับ getters ของคุณโดยไม่ต้องทำซ้ำความคิดเห็น javadoc

ณ ตอนนี้ฉันกำลังพิจารณาทำการฝึกฝนเพื่อจัดทำเอกสารเฉพาะผู้รับไม่ใช่คุณสมบัติ แต่ดูเหมือนไม่ใช่ทางออกที่ดีที่สุด ...

คุณสามารถรวมสมาชิกส่วนตัวขณะสร้าง Javadocs (โดยใช้ -private) จากนั้นใช้ @link เพื่อลิงก์ไปยังคุณสมบัติของฟิลด์นั้น

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

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

หรืออีกวิธีหนึ่งหากคุณไม่ต้องการสร้าง Javadoc สำหรับสมาชิกส่วนตัวทั้งหมดคุณสามารถมีแบบแผนในการจัดทำเอกสาร getters ทั้งหมดและใช้ @link บน 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;
    }
}

ลอมบอกเป็นห้องสมุดที่สะดวกมากสำหรับงานดังกล่าว

@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;
}

นั่นคือทั้งหมดที่คุณต้องการ! @Getterคำอธิบายประกอบสร้างวิธีทะเยอทะยานสำหรับเขตข้อมูลส่วนตัวแต่ละคนและแนบ Javadoc เพื่อมัน

PS : ห้องสมุดมีคุณสมบัติเจ๋ง ๆ มากมายที่คุณอาจต้องการชำระเงิน

ฉันทำทั้งสองอย่างโดยได้รับความช่วยเหลือจากการเติมข้อความอัตโนมัติของ Eclipse

ก่อนอื่นฉันบันทึกทรัพย์สิน:

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

จากนั้นฉันคัดลอกและวางสิ่งนี้ลงใน getter:

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

ด้วย eclipse คำสั่ง @return จะมีการเติมข้อความอัตโนมัติดังนั้นฉันจึงเพิ่มคำว่า Gets ตัวพิมพ์เล็ก "t" และคัดลอกประโยคด้วยตัวพิมพ์เล็ก "t" จากนั้นฉันใช้ @return (พร้อมการเติมข้อความอัตโนมัติ Eclipse) วางประโยคแล้วพิมพ์ตัวพิมพ์ใหญ่ T ในการส่งคืน จากนั้นจะมีลักษณะดังนี้:

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

สุดท้ายฉันคัดลอกเอกสารนั้นไปยัง setter:

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

จากนั้นฉันแก้ไขและด้วยการเติมข้อความอัตโนมัติ Eclipse คุณจะได้รับไม่เพียง แต่แท็ก @param เท่านั้น แต่ยังรวมถึงชื่อของพารามิเตอร์ด้วย:

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

เสร็จแล้ว ในความคิดของฉันแม่แบบนี้ทำให้ง่ายขึ้นมากในระยะยาวไม่เพียง แต่เตือนตัวเองว่าทรัพย์สินมีความหมายอย่างไรผ่านการทำซ้ำ แต่ยังช่วยให้เพิ่มความคิดเห็นเพิ่มเติมให้กับ getter และ setter ได้ง่ายขึ้นหากคุณต้องการเพิ่มด้านข้าง เอฟเฟกต์ (เช่นไม่อนุญาตให้ใช้คุณสมบัติ null เปลี่ยนสตริงเป็นตัวพิมพ์ใหญ่ ฯลฯ ) ฉันตรวจสอบการสร้างปลั๊กอิน Eclipse เพื่อจุดประสงค์นี้ แต่ฉันไม่พบจุดขยายที่เหมาะสมสำหรับ JDT ดังนั้นฉันจึงยอมแพ้

โปรดทราบว่าประโยคอาจไม่ได้ขึ้นต้นด้วย T เสมอไปมันเป็นเพียงตัวอักษรตัวแรกเท่านั้นที่จะต้องไม่มีทุน / เพิ่มทุนในการวาง

ฉันคิดว่ามันเป็นปัญหาจริงๆและคู่มือ Javadocอย่างเป็นทางการไม่ได้บอกอะไรเกี่ยวกับเรื่องนี้ C # สามารถแก้ปัญหานี้ได้อย่างสวยงามด้วยการใช้ Properties (ฉันไม่ได้เขียนโค้ดใน C # แต่ฉันคิดว่ามันเป็นคุณสมบัติที่ดีจริงๆ)

แต่ฉันเดาได้: ถ้าคุณต้องการอธิบายว่า someString คืออะไรบางทีมันอาจจะเป็น `` ขนาดเล็กที่ไม่ดี '' เกี่ยวกับรหัสของคุณ อาจหมายความว่าคุณควรเขียน SomeClass เพื่อพิมพ์ someString ดังนั้นคุณจะอธิบายได้ว่า someString คืออะไรในเอกสาร SomeClass และไม่จำเป็นต้องใช้ javadocs ใน getter / setter