17
มาตรฐานการเข้ารหัสเพื่อความชัดเจน: แสดงความคิดเห็นทุกบรรทัดของรหัส?
ฉันทำงานในร้านค้าที่ผลิตซอฟต์แวร์ที่สำคัญต่อชีวิตและฉันได้จัดการกับกฎการแสดงความคิดเห็นที่ตั้งใจจะให้โค้ดอ่านได้และอาจช่วยชีวิตผู้คนได้ จากประสบการณ์ของฉันแม้ว่าความต้องการจะกลายเป็นงานที่น่าเบื่อสมองที่ต้องทำเครื่องหมายในรายการตรวจสอบและไม่ช่วยให้ฉันจดจ่อกับการเขียนโค้ดที่เข้าใจได้ นอกจากนี้ยังเบี่ยงเบนความสนใจจากผู้ตรวจสอบเพียร์ของฉันจากการสนทนาที่มีความหมายกับฉันมากขึ้นเกี่ยวกับวิธีทำให้โค้ดง่ายต่อการเข้าใจ ฉันให้คะแนนรหัสนักเรียนที่ไม่มีความคิดเห็นและเห็นว่าเพราะเหตุใดพวกเขาจึงควรทำเครื่องหมายเพราะละเลยพวกเขา ฉันเข้าใจว่าการใช้ชื่อที่ดีโครงสร้างที่เรียบง่ายฟังก์ชั่นสั้น ๆ และโมดูลที่มุ่งเน้นจะทำให้โค้ดนั้นเข้าใจได้ง่ายพอที่จะลดความคิดเห็นได้ ฉันยังเข้าใจด้วยว่าความคิดเห็นควรอธิบายว่าทำไมรหัสทำในสิ่งที่มันทำไม่ได้อย่างไร ให้ทั้งหมดนี้เป็นไปได้ที่จะเขียนมาตรฐานการเข้ารหัสที่ดีที่จับความคิดนี้ คนที่จะมีความเกี่ยวข้องในการตรวจสอบโดยเพื่อน แต่จะไม่เปลี่ยนเป็นรายการตรวจสอบที่ไม่สนใจซึ่งทำให้โน้ตไม่เป็นประโยชน์มากกว่า: "คุณลืมแสดงความคิดเห็นในบรรทัดที่ 42" ตัวอย่างประเภทของรหัสกฎนี้อาจต้องใช้เมื่อถือว่าเป็นบรรทัดในรายการตรวจสอบ: /* Display an error message */ function display_error_message( $error_message ) { /* Display the error message */ echo $error_message; /* Exit the application */ exit(); } /* -------------------------------------------------------------------- */ /* Check if the configuration file does …