รหัสเอกสารด้วยตนเองเทียบกับ Javadocs?

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

ฉันมักจะพึ่งพาด้านของความคิดที่ว่าตนเอง documenting รหัสเป็นสิ่งที่ดี ฉันแค่คิดว่ามันสะอาดและถ้ารหัสพูดสำหรับตัวเองดี ... ที่ดี

ในอีกทางหนึ่งเรามีเอกสารเช่น javadocs ฉันชอบสิ่งนี้เช่นกัน แต่มีความเสี่ยงบางอย่างที่ความคิดเห็นที่นี่ล้าสมัย (เช่นเดียวกับความคิดเห็นทั่วไป) อย่างไรก็ตามหากพวกเขาทันสมัยพวกเขาจะมีประโยชน์อย่างมากในการพูดทำความเข้าใจกับอัลกอริทึมที่ซับซ้อน

อะไรคือแนวทางปฏิบัติที่ดีที่สุดสำหรับสิ่งนี้ คุณวาดเส้นระหว่างรหัสการทำเอกสารด้วยตนเองและ javadocs ได้อย่างไร

รหัสการทำเอกสารด้วยตนเอง (และความคิดเห็นในโค้ด) และความคิดเห็น Javadoc มีกลุ่มเป้าหมายที่แตกต่างกันสองกลุ่ม

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

ความคิดเห็น Javadoc โดยทั่วไปแล้วสำหรับผู้ใช้ของ API สิ่งเหล่านี้ยังเป็นนักพัฒนา แต่พวกเขาไม่สนใจโครงสร้างภายในของระบบเพียงแค่คลาสวิธีการอินพุตและเอาต์พุตของระบบ รหัสมีอยู่ในกล่องดำ ความคิดเห็นเหล่านี้ควรใช้เพื่ออธิบายวิธีการทำงานบางอย่างผลลัพธ์ของการดำเนินการที่คาดหวังคืออะไรเมื่อมีการโยนข้อยกเว้นและค่าอินพุตหมายความว่าอย่างไร ด้วยชุดเอกสารที่สร้างขึ้นโดย Javadoc ฉันควรเข้าใจวิธีใช้อินเทอร์เฟซของคุณโดยไม่ต้องดูบรรทัดรหัสของคุณเลย

รหัสกล่าวว่า ความคิดเห็นพูดทำไมและบางทีก็ทำไมไม่

เป็นหน้าที่ของคุณที่จะให้ทั้งผู้อ่านและผู้ดูแลรหัสของคุณในอนาคต ใส่ทั้งหมดที่คุณสามารถทำได้ในรหัสและส่วนที่เหลือในความคิดเห็น

โปรดทราบว่าสิ่งที่ยากที่สุดในการจับภาพคือการตัดสินใจออกแบบ - จำสิ่งเหล่านั้นด้วย

การใช้ Javadocs ไม่ได้สร้างความแตกต่างอย่างแท้จริง - เนื่องจากเอกสารที่สร้างขึ้นมีชื่อฟังก์ชั่นของคุณพร้อมกับข้อความจากความคิดเห็นไม่มีเหตุผลใดที่คุณควรทำซ้ำในความคิดเห็นที่ชัดเจนจากชื่อฟังก์ชันเอง

ถ้าในอีกทางหนึ่งคุณมีฟังก์ชั่นที่จะต้องพิจารณาการใช้งานก่อนเพื่อทำความเข้าใจว่ามันดีสำหรับอะไร (ดังนั้นอย่าให้ข้อมูลนี้แก่ Javadocs) รหัสนั้น IMHO ไม่ใช่การจัดทำเอกสารด้วยตนเอง การนำไปปฏิบัติมีความชัดเจนเพียงใด

ฉันคิดว่าด้วย javadocs สิ่งต่าง ๆ เหมือนกับเอกสารทั้งหมด - กฎหลักคือ:

ติดตามผู้ชม

อย่าหลายคนอ่าน javadocs ของคุณหรือไม่ ถ้าใช่มันเป็นการดีที่จะลงทุนความพยายามในการทำให้ถูกต้อง

ผู้อ่านของคุณมีแนวโน้มที่จะข้ามรหัสการอ่านเพื่อการศึกษา javadocs หรือไม่? ถ้าใช่มันทำให้รู้สึกถึงสองเท่าที่จะใช้ความพยายามในการเขียนได้ดี

• ตรงนี้เป็นกรณีที่มีเอกสาร JDK Guess Sun / Oracle ใช้ความพยายามอย่างมากกับสิ่งเหล่านี้และดูเหมือนว่าพวกเขาจะได้รับผลตอบแทนที่ดีในการใช้งาน API เอกสารจากชุมชน

ตอนนี้เป็นกรณีของคุณหรือไม่ ถ้าไม่ลองคิดดูว่าความพยายามลงทุนใน javadocs นั้นถูกต้องหรือไม่

ตามที่กล่าวไว้ข้างต้นให้ฟังผู้ชมเพื่อหาทาง

• หากคุณได้ยินคำร้องเรียนที่แอ็คทีฟเกี่ยวกับเอกสารไม่เพียงพอให้พิจารณาลงทุนเพื่อปรับปรุงให้ดีขึ้น
   
  ถ้าในมืออื่น ๆ ทั้งหมดที่คุณได้ยินเสียงหอนเป็นนักพัฒนาเกี่ยวกับกฎ braindead บังคับให้พวกเขาต้องเสียเวลาในการพิมพ์ไร้ประโยชน์กันแล้วจึงมีโอกาสสูงที่ความพยายาม javadocs ของคุณเป็นเหมือนการลงทุนในการจำนองซับไพรม์ คิดถึงการลงทุนที่ดีกว่าแทน

ฉันแค่ต้องการที่จะแสดงความคิดเห็นในความกังวลว่าความคิดเห็น Javadoc อาจล้าสมัย ในขณะที่ @JonathanMerlet บอกถูกต้องว่า Javadoc ควรมีเสถียรภาพคุณสามารถช่วยได้โดยการตรวจสอบ Javadoc และความคิดเห็นรวมถึงโค้ดในระหว่างการตรวจสอบโดยเพื่อน ความคิดเห็นตรงกับสิ่งที่รหัสกำลังทำอยู่หรือไม่? ถ้าไม่ใช่ซึ่งไม่ถูกต้องและยืนยันให้นักพัฒนาแก้ไข พยายามสนับสนุนให้ผู้พัฒนารายอื่นทำเช่นเดียวกัน สิ่งนี้จะช่วยให้ไม่เพียง แต่เอกสารประกอบภายนอก (ความคิดเห็น Javadoc) ที่ทันสมัย ​​แต่ยังแสดงความคิดเห็นเกี่ยวกับโค้ดปกติเช่นกัน สิ่งนี้จะช่วยให้นักพัฒนาซอฟต์แวร์ที่เข้ามาหลังจากการปรับโครงสร้างใหม่ของคุณเข้าใจรหัสได้เร็วขึ้นและง่ายขึ้นและทำให้มันง่ายขึ้นในอนาคต

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