ควรเพิ่มข้อคิดเห็น Javadoc ในการใช้งานหรือไม่?

วิธีปฏิบัติที่ถูกต้องในการเพิ่มความคิดเห็น Javadoc ในอินเทอร์เฟซและเพิ่มความคิดเห็นที่ไม่ใช่ Javadoc ในการนำไปใช้งานหรือไม่?

IDE ส่วนใหญ่สร้างข้อคิดเห็นที่ไม่ใช่ JavaDoc สำหรับการใช้งานเมื่อคุณสร้างข้อคิดเห็นโดยอัตโนมัติ วิธีคอนกรีตควรมีคำอธิบายไม่ใช่หรือ?

สำหรับวิธีการที่ใช้งานเท่านั้น (ไม่ลบล้าง) แน่นอนว่าทำไมไม่โดยเฉพาะอย่างยิ่งหากเป็นแบบสาธารณะ

หากคุณมีสถานการณ์ที่เอาชนะและคุณกำลังจะทำซ้ำข้อความใด ๆ ก็ไม่แน่นอน การจำลองแบบเป็นวิธีที่แน่นอนในการทำให้เกิดความคลาดเคลื่อน ด้วยเหตุนี้ผู้ใช้จะมีความเข้าใจที่แตกต่างกันเกี่ยวกับวิธีการของคุณโดยขึ้นอยู่กับว่าพวกเขาตรวจสอบวิธีการใน supertype หรือ subtype ใช้@inheritDocหรือไม่ให้เอกสาร - IDE จะนำข้อความที่มีอยู่ต่ำสุดไปใช้ในมุมมอง Javadoc

นอกจากนี้หากเวอร์ชันการลบล้างของคุณเพิ่มข้อมูลลงในเอกสารของซุปเปอร์ไทป์คุณอาจตกอยู่ในโลกแห่งปัญหา ฉันศึกษาปัญหานี้ในระหว่างเรียนปริญญาเอกและพบว่าโดยทั่วไปแล้วคนทั่วไปจะไม่ทราบข้อมูลเพิ่มเติมในเวอร์ชันที่ลบล้างหากพวกเขากำลังเรียกใช้ผ่าน supertype

การแก้ไขปัญหานี้เป็นหนึ่งในคุณสมบัติหลักของเครื่องมือต้นแบบที่ฉันสร้างขึ้น - เมื่อใดก็ตามที่คุณเรียกใช้เมธอดคุณจะได้รับข้อบ่งชี้ว่าเป้าหมายหรือเป้าหมายที่อาจลบล้างมีข้อมูลสำคัญ (เช่นพฤติกรรมที่ขัดแย้งกัน) ตัวอย่างเช่นเมื่อเรียกใช้การวางบนแผนที่คุณจะได้รับการเตือนว่าหากการนำไปใช้งานของคุณเป็น TreeMap องค์ประกอบของคุณจะต้องเทียบเคียงได้

ทั้งการใช้งานและอินเทอร์เฟซควรมี javadoc ด้วยเครื่องมือบางอย่างคุณสามารถสืบทอดเอกสารของอินเทอร์เฟซด้วยคีย์เวิร์ด @inheritDoc

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

วิธีปฏิบัติที่ดีคือการวาง

/**
 * {@inheritDoc}
 */

เป็น javadoc ของการนำไปใช้งาน (เว้นแต่จะมีการอธิบายเพิ่มเติมเกี่ยวกับรายละเอียดของการนำไปใช้งาน)

โดยทั่วไปเมื่อคุณแทนที่เมธอดคุณจะปฏิบัติตามสัญญาที่กำหนดไว้ในคลาสพื้นฐาน / อินเทอร์เฟซดังนั้นคุณจึงไม่ต้องการเปลี่ยน javadoc ดั้งเดิม แต่อย่างใด ดังนั้นจึงไม่จำเป็นต้องใช้@inheritDocหรือ@seeแท็กที่กล่าวถึงในคำตอบอื่น ๆ และทำหน้าที่เป็นสัญญาณรบกวนในโค้ดเท่านั้น เครื่องมือที่สมเหตุสมผลทั้งหมดสืบทอดวิธีการ javadoc จากซูเปอร์คลาสหรืออินเทอร์เฟซตามที่ระบุไว้ที่นี่ :

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

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

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

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

ทำไม? เนื่องจากความคิดเห็นที่สืบทอดมาอาจมีความยาวมาก ในกรณีนี้ใครจะสังเกตเห็นประโยคเสริมท้ายวรรคยาว 3 ย่อหน้า ?? เพียงแค่เขียนความคิดเห็นของคุณเองและนั่นคือทั้งหมดที่ เครื่องมือ javadoc ทั้งหมดจะแสดงประเภทSpecified by link ซึ่งคุณสามารถคลิกเพื่ออ่านความคิดเห็นของคลาสพื้นฐานได้ ไม่มีประเด็นในการผสมพวกเขา

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

Sjoerd บอกอย่างถูกต้องว่าทั้งอินเทอร์เฟซและการนำไปใช้งานควรมี JavaDoc อินเทอร์เฟซ JavaDoc ควรกำหนดสัญญาของเมธอด - สิ่งที่เมธอดควรทำสิ่งที่อินพุตต้องใช้ค่าใดที่ควรส่งคืนและสิ่งที่ควรทำในกรณีที่เกิดข้อผิดพลาด

เอกสารการดำเนินการควรจดบันทึกส่วนขยายหรือข้อ จำกัด ในสัญญาและรายละเอียดที่เหมาะสมของการใช้งานโดยเฉพาะประสิทธิภาพ

เพื่อประโยชน์ในการสร้าง javadoc ใช่มันไม่สำคัญ หากคุณประกาศการอ้างอิงถึงการนำไปใช้งานที่เป็นรูปธรรมโดยใช้เฉพาะอินเทอร์เฟซนั้นจะไม่ได้เนื่องจากวิธีการของอินเทอร์เฟซจะถูกดึงโดย IDE