คอมเมนต์ Getter / Setter ง่ายๆ

คุณใช้หลักการใดในการแสดงความคิดเห็นผู้รับและผู้ตั้งถิ่นฐาน? นี่เป็นสิ่งที่ฉันสงสัยมาระยะหนึ่งแล้วเช่น:

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

ฉันมักจะพบว่าฉันมักจะเขียนสิ่งเดียวกันสำหรับ 1a / b และ 2a / b เช่น 1a) กำหนดเงินเดือนของพนักงาน 1b) เงินเดือนของพนักงาน ดูเหมือนซ้ำซ้อนมาก ตอนนี้ฉันเห็นบางอย่างที่ซับซ้อนกว่านี้คุณอาจเขียนเพิ่มเติมในส่วน (a) เพื่อให้บริบท แต่สำหรับ getters / setters ส่วนใหญ่คำพูดนั้นเกือบจะเหมือนกันทุกประการ

ฉันแค่อยากรู้ว่าสำหรับ getters / setters แบบธรรมดามันตกลงที่จะกรอกเฉพาะส่วน (a) หรือส่วน (b)

คุณคิดอย่างไร?

ฉันมักจะเติมส่วนพารามิเตอร์สำหรับ setters และส่วน @return สำหรับ getters:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

ด้วยวิธีนี้เครื่องมือตรวจสอบ javadoc (เช่นคำเตือนของ Eclipse) จะออกมาสะอาดและไม่มีการทำซ้ำ

ไม่มีจุดหมายอย่างแน่นอน - คุณจะดีกว่าโดยไม่มีอึแบบนี้มาเกะกะรหัสของคุณ:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

มีประโยชน์มากหากได้รับการรับรอง:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

โดยเฉพาะอย่างยิ่งคำอธิบายเกี่ยวกับความหมายของคุณสมบัติที่แท้จริงอาจมีความสำคัญอย่างยิ่งในโมเดลโดเมน เมื่อใดก็ตามที่ฉันเห็นถั่วที่เต็มไปด้วยคุณสมบัติที่มีชื่อคลุมเครือซึ่งมีเพียงวาณิชธนกิจนักชีวเคมีหรือนักฟิสิกส์ควอนตัมเท่านั้นที่เข้าใจและความคิดเห็นอธิบายว่าวิธี setGobbledygook () "กำหนด gobbledygook" ฉันต้องการบีบคอใครบางคน

โดยทั่วไปไม่มีอะไรถ้าฉันสามารถช่วยได้ ผู้รับและผู้ตั้งค่าควรเป็นผู้อธิบายตนเอง

ฉันรู้ว่าฟังดูเหมือนไม่ใช่คำตอบ แต่ฉันพยายามใช้เวลาแสดงความคิดเห็นในสิ่งที่ต้องการคำอธิบาย

ฉันจะบอกว่าเพียงกังวลเกี่ยวกับการแสดงความคิดเห็น getters และ setters หากมีผลข้างเคียงบางอย่างหรือต้องการเงื่อนไขเบื้องต้นบางอย่างนอกเหนือจากการเริ่มต้น (เช่นการรับจะลบรายการออกจากโครงสร้างข้อมูลหรือเพื่อกำหนดสิ่งที่คุณต้องการ ให้มี x และ y อยู่ในตำแหน่งก่อน) มิฉะนั้นความคิดเห็นที่นี่จะค่อนข้างซ้ำซ้อน

แก้ไข: นอกจากนี้หากคุณพบว่ามีผลข้างเคียงมากมายที่เกี่ยวข้องกับ getter / setter ของคุณคุณอาจต้องการเปลี่ยน getter / setter ให้มีชื่อวิธีการอื่น (เช่น push and pop สำหรับ stack) [ขอบคุณสำหรับ ความคิดเห็นด้านล่าง]

ถามตัวเองว่าคุณต้องการให้คนอื่นเห็นอะไรเมื่อความคิดเห็นถูกมองว่าเป็น JavaDocs (จากเบราว์เซอร์) หลายคนบอกว่าเอกสารไม่จำเป็นเนื่องจากชัดเจน สิ่งนี้จะไม่ถือหากฟิลด์นั้นเป็นแบบส่วนตัว (เว้นแต่คุณจะเปิด JavaDocs สำหรับฟิลด์ส่วนตัวไว้อย่างชัดเจน)

ในกรณีของคุณ:

public void setSalary(float s)
public float getSalary()

ยังไม่ชัดเจนว่าเงินเดือนที่แสดงเป็นเซนต์ดอลลาร์ปอนด์ RMB?

เมื่อจัดทำเอกสาร setters / getters ฉันต้องการแยกสิ่งที่ออกจากการเข้ารหัส ตัวอย่าง:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

บรรทัดแรกบอกว่าจะคืนค่าความสูง พารามิเตอร์การส่งคืนเอกสารที่ความสูงเป็นเมตร

ทำไมพวกเขาไม่เพียงแค่ใส่แท็กอ้างอิงเพื่อให้คุณสามารถแสดงความคิดเห็นค่าฟิลด์และข้อมูลอ้างอิงจาก getters และ setters

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

เพื่อให้เอกสารนำไปใช้กับ getter และ setter ตลอดจนฟิลด์ (ถ้าเปิด javadocs ส่วนตัวอยู่)

ชนิดของต้นแบบนี้สามารถหลีกเลี่ยงโดยใช้โครงการลอมบอก เพียงแค่บันทึกตัวแปรฟิลด์แม้ว่าจะเป็นprivateและปล่อยให้คำอธิบายประกอบ Lombok สร้างตัวรับและตัวตั้งค่าที่มีการบันทึกไว้อย่างถูกต้อง

สำหรับผมได้รับประโยชน์นี้เพียงอย่างเดียวมีมูลค่าค่าใช้จ่าย

ฉันผิดหวังมากกับคำตอบโดยทั่วไปที่บอกว่าการจัดทำเอกสารที่ครอบคลุมนั้นเสียเวลา วิธีการที่ลูกค้าของ API ของคุณควรจะรู้ว่าวิธีการที่เรียกว่าsetXเป็นมาตรฐานคุณสมบัติหมา JavaBeanเว้นแต่คุณพูดอย่างชัดเจนในเอกสาร ?

หากไม่มีเอกสารผู้โทรจะไม่รู้ว่าวิธีการนี้มีผลข้างเคียงใด ๆ นอกเหนือจากการข้ามนิ้วของพวกเขาเกี่ยวกับการประชุมที่ชัดเจนที่กำลังจะตามมา

ฉันแน่ใจว่าฉันไม่ใช่คนเดียวที่นี่ที่มีความโชคร้ายในการค้นหาวิธีที่ยากที่วิธีการที่เรียกว่าsetXทำอะไรได้มากกว่าการตั้งค่าคุณสมบัติ

หากไม่มีการดำเนินการพิเศษใน getter / setter ฉันมักจะเขียน:

ด้วย Javadoc (พร้อมตัวเลือกส่วนตัว):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

และ / หรือ

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

ด้วย Doxygen (พร้อมตัวเลือกสารสกัดส่วนตัว):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

ผู้เข้าถึงการแสดงความคิดเห็นโดยเฉพาะอย่างยิ่งหากพวกเขาไม่ได้ดำเนินการใด ๆ ที่ใดก็ไม่จำเป็นและสิ้นเปลืองปลายนิ้ว

หากมีคนอ่านรหัสของคุณไม่เข้าใจว่าperson.getFirstName()ส่งคืนชื่อของบุคคลคุณควรพยายามทำทุกอย่างเพื่อให้เขาถูกไล่ออก หากใช้เวทมนตร์ในฐานข้อมูลให้โยนลูกเต๋าสองสามลูกเรียกเลขาธิการแห่งชื่อเพื่อรับชื่อจริงมันปลอดภัยที่จะถือว่าเป็นการดำเนินการที่ไม่สำคัญและบันทึกไว้อย่างดี

ถ้าในทางกลับกันคุณperson.getFirstName()ไม่คืนชื่อของบุคคลนั้น ... ดีไม่ไปที่นั่นเราจะ?

อย่าใส่อะไรเลยหากชื่อฟิลด์นั้นสื่อความหมายได้อย่างชัดเจนถึงเนื้อหา

โดยทั่วไปให้รหัสมีจุดยืนในตนเองและหลีกเลี่ยงการแสดงความคิดเห็นหากเป็นไปได้ อาจต้องมีการปรับโครงสร้างใหม่

แก้ไข: ข้างต้นหมายถึง getters และ setters เท่านั้น ฉันเชื่อว่าอะไรก็ตามที่ไม่สำคัญควรได้รับการ javadoc'ed อย่างถูกต้อง

คุณสามารถกรอกข้อมูลในส่วน (b) ได้โดยเฉพาะอย่างยิ่งถ้าคุณใส่ความคิดเห็นในการประกาศเขตข้อมูลที่ระบุว่าฟิลด์นั้นเกี่ยวกับอะไร

หาก javadoc ไม่ได้เพิ่มอะไรฉันจะลบ javadoc และใช้ความคิดเห็นที่สร้างขึ้นโดยอัตโนมัติ

ฉันมักจะกรอกทั้งสองอย่าง เวลาที่ใช้ในการพิมพ์เพิ่มเติมนั้นน้อยมากและโดยทั่วไปแล้วข้อมูลจะดีกว่าน้อยกว่า