วิธีที่ดีที่สุดสำหรับความคิดเห็นโค้ดอินไลน์คืออะไร

เรากำลังทำการปรับเปลี่ยนบางอย่างให้เป็น codebase เก่าแก่อายุ 20 ปีและฉันกำลังพูดคุยกับเพื่อนร่วมงานของฉันเกี่ยวกับรูปแบบความคิดเห็นในรหัส (plsql, java)

ไม่มีรูปแบบเริ่มต้นสำหรับความคิดเห็น แต่ในกรณีส่วนใหญ่คนทำสิ่งนี้ในความคิดเห็น:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

รูปแบบที่เสนอสำหรับความคิดเห็นในอนาคตและในอดีตที่ฉันต้องการคือ:

// {yyyy-mm-dd}, unique_author_company_id, comment

เพื่อนร่วมงานของฉันบอกว่าเราต้องการเพียงความคิดเห็นเท่านั้นและต้องจัดรูปแบบความคิดเห็นทั้งในอดีตและอนาคตในรูปแบบนี้:

// comment

ข้อโต้แย้งของฉัน:

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

ข้อโต้แย้งของเพื่อนร่วมงานของฉัน:

• ประวัติอยู่ใน SCM
• นักพัฒนาจะต้องไม่ทราบประวัติของรหัสโดยตรงในรหัส
• แพ็คเกจมีความยาว 15k บรรทัดและความคิดเห็นที่ไม่มีโครงสร้างทำให้แพ็คเกจเหล่านี้ยากต่อการเข้าใจ

คุณคิดว่าวิธีใดดีที่สุด? หรือคุณมีแนวทางที่ดีกว่าในการแก้ปัญหานี้?

ข้อคิดเห็นทั่วไป

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

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

จะผ่านข้อโต้แย้ง:

ฉันพูดด้วยเหตุผลด้านการบำรุงรักษาสิ่งสำคัญคือต้องรู้ว่าเมื่อใดและใครทำการเปลี่ยนแปลง (แม้ข้อมูลนี้จะอยู่ใน SCM)

ทำไม. ไม่มีสิ่งใดที่ทำให้ฉันมีความสำคัญต่อการรักษารหัส หากคุณต้องการพูดคุยกับผู้เขียนมันค่อนข้างง่ายในการค้นหาข้อมูลจากแหล่งควบคุม

รหัสมีชีวิตด้วยเหตุผลนั้นมีประวัติ

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

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

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

เนื่องจากผู้เขียนมีความสำคัญมากการเปลี่ยนแปลงของ authorx จึงมีความน่าเชื่อถือมากกว่าการเปลี่ยนแปลง Authory

ผู้เขียนทั้งหมด (นอกเหนือจากตัวคุณเอง) มีความน่าเชื่อถือเท่า ๆ กัน

เหตุผลความว่องไวไม่จำเป็นต้องเปิดเครื่องมือนำทาง SCM

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

ผู้คนจะกลัวการเปลี่ยนแปลงบางอย่างที่ใครบางคนทำเมื่อ 15 ปีที่แล้วกว่าบางครั้งที่สร้างขึ้น ...

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

เหตุผลมากขึ้นในการใช้การควบคุมแหล่งที่มาเพื่อรับข้อมูล

ประวัติอยู่ใน SCM

ใช่. เหตุผลที่ดีที่สุด

นักพัฒนาจะต้องไม่ทราบประวัติของรหัสโดยตรงในรหัส

ถ้าฉันต้องการข้อมูลนี้จริงๆฉันจะค้นหามันในการควบคุมแหล่งที่มา
มิฉะนั้นจะไม่เกี่ยวข้อง

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

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

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

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

ท้ายที่สุดคุณจ้างโปรแกรมเมอร์ไม่ใช่นักเล่าเรื่อง ;-)