จำเป็นต้องเขียนความคิดเห็น javadoc สำหรับพารามิเตอร์ EVERY ในลายเซ็นของเมธอดหรือไม่?

หนึ่งในทีมของฉันเชื่อว่าจำเป็นต้องเขียนความคิดเห็น javadoc สำหรับพารามิเตอร์ EVERY ในลายเซ็นของเมธอด ฉันไม่คิดว่ามันเป็นสิ่งจำเป็นและอันที่จริงฉันคิดว่ามันอาจเป็นอันตรายได้

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

แต่ฉันคิดว่ามันไม่จำเป็นที่จะทำเช่นนั้นสำหรับพารามิเตอร์ทุกคน หากเห็นได้ชัดว่าพารามิเตอร์สำหรับความคิดเห็น javadoc นั้นซ้ำซ้อน; คุณกำลังสร้างงานพิเศษสำหรับตัวคุณเอง นอกจากนี้คุณกำลังสร้างงานพิเศษสำหรับทุกคนที่ต้องรักษารหัสของคุณ วิธีการเปลี่ยนแปลงเมื่อเวลาผ่านไปและการบำรุงรักษาความคิดเห็นเกือบจะสำคัญเท่ากับการบำรุงรักษาโค้ดของคุณ มีกี่ครั้งที่คุณเห็นความคิดเห็นเช่น "X ทำ Y เพื่อ Z เหตุผล" เพียงเพื่อดูว่าความคิดเห็นนั้นล้าสมัยและในความเป็นจริงวิธีการไม่ได้ใช้พารามิเตอร์ X อีกต่อไป? มันเกิดขึ้นตลอดเวลาเพราะคนลืมที่จะอัพเดทความคิดเห็น ฉันจะยืนยันว่าความคิดเห็นที่ทำให้เข้าใจผิดเป็นอันตรายมากกว่าความคิดเห็นที่ไม่ทั้งหมด และดังนั้นจึงเป็นอันตรายของการแสดงความคิดเห็นมากเกินไป: โดยการสร้างเอกสารที่ไม่จำเป็นคุณจะต้อง

อย่างไรก็ตามฉันเคารพนักพัฒนาคนอื่นในทีมของฉันและยอมรับว่าบางทีเขาอาจจะพูดถูกและฉันผิด ทำไมฉันถึงนำคำถามมาให้คุณผู้พัฒนาเพื่อน: จำเป็นต้องเขียนความคิดเห็น javadoc สำหรับพารามิเตอร์ EVERY หรือไม่? สมมติว่านี่เป็นรหัสภายใน บริษัท ของฉันและบุคคลภายนอกใด ๆ จะไม่ถูกใช้

javadoc (และในคำว่าไมโครซอฟท์ XMLDOC) คำอธิบายประกอบไม่ได้แสดงความคิดเห็นที่พวกเขามีเอกสาร

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

เอกสารแสดงให้เห็นถึงการทำสัญญาระหว่างหน่วยของรหัสและโทรติดต่อของ มันเป็นส่วนหนึ่งของ API สาธารณะ สันนิษฐานเสมอว่า Javadoc / XMLdoc จะลงเอยในไฟล์ช่วยเหลือหรือในป๊อปอัปการเติมข้อความอัตโนมัติ / intellisense / code-completion และสังเกตได้โดยคนที่ไม่ได้ตรวจสอบภายในของรหัสของคุณ แต่ต้องการใช้เพื่อวัตถุประสงค์บางอย่างของ ด้วยตัวของพวกเขาเอง.

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

อย่าเข้าใจฉันผิด - เป็นสิ่งสำคัญที่จะต้องเลือกชื่อที่มีความหมายสำหรับตัวแปรและข้อโต้แย้ง แต่นั่นเป็นข้อกังวลเกี่ยวกับรหัสไม่ใช่ข้อกังวลเกี่ยวกับเอกสาร อย่าใช้วลี "การจัดทำเอกสารด้วยตนเอง" อย่างแท้จริงเช่นกัน ที่มีความหมายในบริบทของเอกสารภายใน (ความคิดเห็น) ไม่ใช่เอกสารภายนอก (สัญญา)

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

จำไว้ว่า: บางสิ่งที่เหมาะสมกับคุณอาจถูกตีความแตกต่างไปจากเดิมอย่างสิ้นเชิงไม่ว่าคุณจะคิดว่ามันธรรมดาแค่ไหน (คิดว่าคนที่ไม่เก่งในการอ่านภาษาอังกฤษและพยายามเข้าใจรหัสของคุณ)

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

เริ่มจากสมมติฐานที่ว่าวัฏจักรนักพัฒนาเป็นทรัพยากรที่เราพยายามอนุรักษ์

นั่นหมายความว่า devs ไม่ควรเสียเวลากับการบันทึกพารามิเตอร์ที่เห็นได้ชัดในตัวเองและคืนค่าใช่มั้ย

เรามาทำลายมันกัน

ถ้าเราทำเอกสารทุกอย่างสมมติว่าความคิดเห็นเล็กน้อยนั้นไม่สำคัญและไม่ต้องคิดหรือวิจัยค่าใช้จ่ายคือเวลาเพิ่มในการพิมพ์ความคิดเห็นและแก้ไขการพิมพ์ผิด

หากเราเลือกและเลือกค่าใช้จ่ายคือ:

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

ดังนั้นฉันอยากจะทำเอกสารทุกอย่าง ข้อเสียคือแน่นอน แต่มีอยู่

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

สำหรับการบำรุงรักษา Javadoc อย่างถูกต้องคุณต้องใช้เครื่องมือสำหรับการพัฒนาของคุณที่ช่วยคุณในเรื่องนี้ คราสมาถึงใจ แน่นอนถ้าเป็นเรื่องสำคัญคุณต้องให้แน่ใจว่าทุกคนในทีมทำส่วนของพวกเขาเพื่อรักษารหัสรวมถึงความคิดเห็น

อย่าลืมว่า javadoc สามารถมองเห็นได้ในขณะที่แยกจากโค้ดตัวอย่างที่สำคัญคือJava APIเอง โดยไม่รวม javadoc สำหรับทุกพารามิเตอร์ในวิธีการที่คุณนำเสนอวิธีการที่ผิดและวิธีการที่อาจนำมาใช้

'จำเป็น' เป็นอัตนัยอย่างสมบูรณ์ ฉันคิดว่าสิ่งที่คุณถามคือ 'ในสถานการณ์ของคุณคุณควรเพิ่มความคิดเห็น javadoc' ไม่ทราบขอบเขตหรือบริบทของแอพของคุณเราจะรู้ได้อย่างไรว่าอะไรเหมาะสมกับคุณ

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