หนึ่งความคิดเห็นควรแตกต่างกันในภาษาที่ใช้งานได้หรือไม่? [ปิด]

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

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

วิธีที่ถูกต้องในการแสดงความคิดเห็นโปรแกรมการทำงานคืออะไร? ฉันควรใช้วิธีการเดียวกันในการเขียนโปรแกรมซ้ำหรือไม่

ชื่อฟังก์ชั่นควรพูดในสิ่งที่คุณกำลังทำ

การใช้งานจะบอกคุณว่าคุณกำลังทำอะไรอยู่

ใช้ความคิดเห็นเพื่ออธิบายว่าทำไมคุณถึงทำเช่นนั้น

มีแน่นอนเป็นจุดในคำถามนี้เป็นโปรแกรมที่ทำงานมักจะอยู่ในระดับที่เป็นนามธรรมที่แตกต่างกว่าคนที่มีความจำเป็น

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

// map 'toUpperCase' over 'container' yielding 'result'
Container result = new Container();
for (int i=0; i < container.size(); i++) { 
             result.addToTail(container.atElement(i).toUpperCase());
}

แต่นี่เป็นเรื่องไร้สาระอย่างชัดเจนในภาษาที่ใช้งานได้:

-- map 'toUpperCase' over 'list'
let result = map toUpperCase list

ที่ดีกว่า:

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list

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

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

// returns a list of Employees    <-- not necessary
def GetEmployeeList: ...

// returns a list of Employees sorted by last name    <-- necessary
def GetEmployeeList: ...

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

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

ที่กล่าวว่าผมไม่เห็นเหตุผลว่าทำไมความคิดเห็นควรต่อ seจะแตกต่างกันในภาษาทำงาน

ฉันใช้แนวทางเดียวกันในการบันทึกรหัสทั้งหมดของฉัน:

• ใช้ชื่อที่สื่อความหมาย
• เพิ่มความคิดเห็นก่อนตรรกะที่ซับซ้อนพอสมควรหากตรรกะที่ซับซ้อนไม่สามารถหลีกเลี่ยงได้
• เขียนภาพรวมของทั้งระบบ

หากชื่อและประเภทลายเซ็นไม่ได้บอกคุณอย่างชัดเจนว่าฟังก์ชันทำอะไรคุณมักทำผิด

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