บันทึกเหตุผลการปฏิเสธโค้ด: แนวทางจัดการข้อตัดสินใจซอฟต์แวร์

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

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

ภาพประกอบจากคลังภาพสต็อก ไม่ใช่ภาพจากเหตุการณ์จริง

ลองพิจารณาตัวอย่างขั้นตอนง่ายๆ ผ่านการใช้ไฟล์ Markdown ภายในคลังโค้ดของคุณ สมมติว่าฟังก์ชัน load_profile ในไฟล์ src/cache.py ทำหน้าที่ดึงข้อมูลโพรไฟล์จากฐานข้อมูลที่ใช้งานร่วมกัน และคุณกำลังพิจารณาแนวทางแคชข้อมูลแบบ process-local แต่ติดปัญหาเรื่องความสอดคล้องของข้อมูลระหว่างเธิร์ดเพอร์สัน

รูปแบบโครงสร้างไฟล์บันทึกข้อตัดสินใจใน docs/decisions/cache-001.md สามารถเขียนระบุรายละเอียดได้ดังนี้: