Architectural Decision Records (บันทึกการตัดสินใจด้าน Architecture)

หนึ่งในวิธีที่มีประสิทธิภาพที่สุดในการบันทึกการตัดสินใจด้าน architecture คือการใช้ Architectural Decision Records ( ADR ) Michael Nygard เป็นคนแรกที่เผยแพร่แนวคิด ADR ใน blog post ปี 2011 และในปี 2017 Thoughtworks Technology Radar ก็แนะนำเทคนิคนี้ให้นำไปใช้อย่างแพร่หลาย

ADR ประกอบด้วยไฟล์ข้อความสั้น ๆ (โดยปกติยาวประมาณหนึ่งถึงสองหน้า) ที่อธิบายการตัดสินใจด้าน architecture แบบเจาะจง แม้ ADR จะเขียนเป็น plain text หรือใน wiki page template ได้ แต่โดยปกติมักเขียนในรูปแบบเอกสาร ข้อความบางอย่าง เช่น AsciiDoc หรือ Markdown

มีเครื่องมือสำหรับจัดการ ADR ให้ใช้ด้วยเช่นกัน Nat Pryce ผู้เขียนร่วมของหนังสือ Growing Object-Oriented Software, Guided by Tests (Addison-Wesley, 2009) ได้เขียนเครื่องมือ open source ชื่อ ADR Tools ที่ให้ command-line interface สำหรับจัดการ ADR รวมถึงระบบการนับเลข, ตำแหน่งที่เก็บ และ logic การแทนที่ Micha Kops วิศวกรซอฟต์แวร์จากเยอรมนี ได้ให้ ตัวอย่างที่ดี เกี่ยวกับการใช้ ADR tools เพื่อจัดการ architectural decision record

Basic Structure (โครงสร้างพื้นฐาน)

โครงสร้างพื้นฐานของ ADR ประกอบด้วยห้าส่วนหลัก ได้แก่ Title , Status , Context , Decision และ Consequences เรามักจะเพิ่มอีกสองส่วนเป็นส่วนหนึ่งของโครงสร้างพื้นฐาน ได้แก่ Compliance และ Notes ส่วน Compliance เป็นพื้นที่สำหรับคิดและบันทึกว่าการตัดสินใจด้าน architecture จะถูก govern และบังคับใช้ อย่างไร (แบบ manual หรือผ่าน fitness function อัตโนมัติ) ส่วน Notes เป็นพื้นที่สำหรับใส่ metadata เกี่ยวกับการตัดสินใจ เช่น ผู้เขียน, ผู้อนุมัติ, วันที่สร้าง และอื่น ๆ

การขยายโครงสร้างพื้นฐานนี้ (ดังแสดงใน Figure 21-2 ) ให้รวมส่วนอื่น ๆ ที่จำเป็นก็ทำได้ ขอแค่รักษา template ให้สม่ำเสมอและกระชับ ตัวอย่างที่ดีอาจเป็นการ เพิ่มส่วน Alternatives เพื่อวิเคราะห์ solution ที่เป็นไปได้อื่น ๆ ทั้งหมด

Figure 21-2. Basic ADR structure

Title (Title)

ชื่อ ADR มักจะถูกนับเลขเรียงลำดับและมีวลีสั้น ๆ ที่อธิบายการตัดสินใจด้าน architecture ตัวอย่างเช่น ชื่อ ADR ที่อธิบายการตัดสินใจใช้ asynchronous messaging ระหว่าง Order service กับ Payment service อาจเขียนว่า “42. Use of Asynchronous Messaging Between Order and Payment Services.” ชื่อควรสั้นและกระชับ แต่ก็ต้องอธิบายได้ชัดเจนพอที่จะขจัดความคลุมเครือเกี่ยวกับลักษณะและบริบทของ การตัดสินใจนั้น

Status (Status)

ADR ทุกฉบับจะมีสถานะหนึ่งในสามแบบ ได้แก่ Proposed , Accepted หรือ Superseded สถานะ Proposed หมายความว่าการตัดสินใจต้องได้รับการอนุมัติจากผู้ตัดสินใจระดับสูงกว่า หรือหน่วยงาน governance ด้าน architecture บางประเภท (เช่น architecture review board) Accepted หมายความว่า การตัดสินใจได้รับการอนุมัติแล้วและพร้อม implement Superseded หมายความว่าการตัดสินใจถูกเปลี่ยนแปลง และถูกแทนที่ด้วย ADR อีกฉบับ สถานะ Superseded จะสมมติเสมอว่าสถานะของ ADR ก่อนหน้าคือ Accepted กล่าวอีกนัยหนึ่งคือ ADR ที่มีสถานะ Proposed จะไม่ถูก supersede โดย ADR อีกฉบับเลย แต่จะถูกแก้ไข ไปเรื่อย ๆ จนกว่าจะกลายเป็น Accepted

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

ตัวอย่างเช่น สมมติว่า ADR 42 (“Use of Asynchronous Messaging Between Order and Payment Services”) อยู่ในสถานะ Approved เนื่องจากการเปลี่ยนแปลงในภายหลังต่อ implementation และตำแหน่งของ Payment service คุณจึงตัดสินใจว่าควรใช้ REST ระหว่างสอง service นี้แทน คุณจึงสร้าง ADR ใหม่ (หมายเลข 68) เพื่อบันทึกการตัดสินใจที่เปลี่ยนแปลงนี้ สถานะที่สอดคล้องกันจะเป็นดังนี้

ADR 42. Use of Asynchronous Messaging Between Order and Payment Services

Status: Superseded by 68

ADR 68. Use of REST Between Order and Payment Services

Status: Accepted, supersedes 42

link และร่องรอยประวัติระหว่าง ADR 42 กับ 68 ช่วยให้คุณหลีกเลี่ยงคำถามที่หลีกเลี่ยงไม่ได้อย่าง “แล้วทำไมไม่ใช้ messaging ล่ะ?” เกี่ยวกับ ADR 68