คู่มือสำหรับผู้เริ่มต้นเพื่อเขียนความคิดเห็น?

มีคำแนะนำที่ชัดเจนเกี่ยวกับการเขียนความคิดเห็นของรหัสมุ่งเป้าไปที่นักพัฒนารุ่นหรือไม่

เป็นการดีที่มันจะครอบคลุมเมื่อความคิดเห็นควร (และไม่ควรใช้) และสิ่งที่ควรมีความคิดเห็น

คำตอบนี้ :

อย่าแสดงความคิดเห็นว่าคุณกำลังทำอะไร แต่ทำไมคุณถึงทำเช่นนั้น

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

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

อัปเดต : นอกเหนือจากคำตอบที่นี่ฉันคิดว่าคำตอบของคำถามอื่นนั้นมีความเกี่ยวข้องสูง

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

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

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

Code Complete ดังที่กล่าวมามีแนวทางต่าง ๆ เกี่ยวกับการเขียนความคิดเห็น กล่าวโดยย่อคือ PDL และสามารถสรุปได้ดังนี้:

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

2. เขียนรหัสเทียม (เช่นความคิดเห็น) ก่อนจากนั้นจึงเขียนรหัสจริงหลังจากที่คุณได้อธิบายกิจวัตร / วิธีการ / ฟังก์ชั่นของคุณเสร็จแล้ว ภาษาที่ใช้นั้นมีระดับสูง แต่มีความเฉพาะเจาะจงดังนั้นจึงค่อนข้างละเอียด

3. มีความคิดว่าโค้ดของคุณทำอะไรอยู่ก่อนจะเขียนโค้ด

4. มีความคิดเห็นใกล้เคียงกับรหัสจริง

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

มีลิงค์ที่ GameDev.net [ซึ่งอธิบาย PDL] [1] ในกรณีที่คุณไม่ต้องการติดตามหนังสือเล่มนี้

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

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

ฉันชอบวิธีที่ Evan Todd สรุปมุมมองของเขาในหมวดหมู่ความคิดเห็นที่เป็นประโยชน์เท่านั้น ( อ้างอิงจากบล็อกของเขา ):

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