ฉันต้องการเขียน Javadoc ด้วยวิธี DRY แต่เอกสาร oracle เกี่ยวกับJavadocกล่าวว่าเขียนสิ่งเดียวกันอีกครั้งในความคิดเห็นของเมธอด overload ฉันไม่สามารถหลีกเลี่ยงการทำซ้ำได้หรือไม่
ฉันต้องการเขียน Javadoc ด้วยวิธี DRY แต่เอกสาร oracle เกี่ยวกับJavadocกล่าวว่าเขียนสิ่งเดียวกันอีกครั้งในความคิดเห็นของเมธอด overload ฉันไม่สามารถหลีกเลี่ยงการทำซ้ำได้หรือไม่
คำตอบ:
ฉันโรย{@inheritDoc}คำสั่งที่นี่และมีในความคิดเห็น Javadoc ของฉันเมื่อเอาชนะวิธีการจาก superclasses หรือการใช้วิธีการกำหนดอินเตอร์เฟส
วิธีนี้ใช้ได้ผลดีสำหรับฉันอย่างน้อยหลีกเลี่ยงการทำซ้ำในซอร์สโค้ดและคุณยังสามารถเพิ่มข้อมูลเฉพาะลงในความคิดเห็น Javadoc เฉพาะหากมีความจำเป็นต้องทำ ฉันไม่พิจารณาข้อเท็จจริงที่ว่าความคิดเห็นของ Javadoc นั้นเปลือยเปล่าพอสมควรที่จะมีปัญหาใด ๆ เมื่อสิ่งที่ใช้ใน IDE ที่เหมาะสมคือการวางเมาส์เหนือชื่อตัวระบุที่เกี่ยวข้องเพื่อให้ Javadoc แสดงผลพร้อมการอ้างอิงและทั้งหมด
จุดประสงค์ของเอกสารคือการให้ความสว่างแก่ผู้ใช้ในอนาคตของรายการ นี่เป็นส่วนหนึ่งเพื่อความสะดวกของผู้เขียนเพื่อที่เขาหรือเธอจะไม่ได้รับการติดต่อเมื่อใดก็ตามที่มีคนไม่สามารถหาวิธีใช้งานได้ อย่างไรก็ตามส่วนใหญ่มันเป็นไปเพื่อประโยชน์ของคนที่ต้องใช้หรือสนับสนุนสิ่งที่
ดังนั้นประเด็นนี้ควรมีความชัดเจนซึ่งตรงข้ามกับความสะดวกสำหรับผู้เขียน คุณไม่สามารถคาดหวังให้คนอื่น ๆ ตามล่าหาเอกสาร API ของคุณได้เพราะคุณขี้เกียจเกินไปที่จะทำซ้ำตัวเอง ดูดมัน - Javadoc จะทำซ้ำ
ที่กล่าวมานั้นไม่มีเหตุผลหากคุณฉลาดคุณไม่สามารถเขียนโปรแกรมที่จะใส่ความคิดเห็นลงในโค้ดของคุณตามเครื่องหมายหรือเกณฑ์อื่น ๆ อาจเป็นปัญหามากกว่าที่ควรค่า หรือไม่.