ฉันเข้าร่วมโครงการขนาดกลางซึ่งทำงานมาหลายปีแล้ว หนึ่งในปัญหาคือเอกสารที่อธิบายสถาปัตยกรรมไม่เคยเขียน ตอนนี้ฉันได้รับมอบหมายให้เขียนคำอธิบายสถาปัตยกรรม

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

ตัวอย่างเช่น GUI ควรเป็นเลเยอร์บาง ๆ โดยไม่มีตรรกะทางธุรกิจ นั่นคือสิ่งที่ฉันบอก การใช้งานประกอบด้วยตรรกะมากมาย

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

ดังนั้นฉันจะอธิบายปัญหาเหล่านี้ได้ที่ไหน ซอฟต์แวร์ติดตามบัก หรือฉันควรอธิบายการเบี่ยงเบนของการใช้งานจากสถาปัตยกรรมในเอกสารที่อธิบายถึงสถาปัตยกรรมของระบบ?

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

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

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

เอกสารนี้ควรเป็นเอกสารที่มีชีวิตที่ใช้เพื่อเป็นแนวทางในการวางแผนและออกแบบการเปลี่ยนแปลงในอนาคตและปรับปรุงตามนั้นภายในกระบวนการพัฒนาของคุณ เมื่อการออกแบบเปลี่ยนแปลงและพัฒนาไปตามกาลเวลาเอกสารควรช่วยให้นักพัฒนาเข้าใจว่าทำไมสิ่งต่าง ๆ ถึงเป็นในปัจจุบัน

หากคุณกำลังมองหาคำแนะนำเกี่ยวกับการจับภาพสถาปัตยกรรมฉันชอบแนวทางที่สนับสนุนในมาตรฐาน IEEE 1016-2009 มาตรฐาน IEEE สำหรับเทคโนโลยีสารสนเทศ - การออกแบบระบบ - การออกแบบซอฟต์แวร์คำอธิบายซอฟแวร์การออกแบบรายละเอียด มันมีโครงสร้างที่เหมาะสมสำหรับคำอธิบายการออกแบบซึ่งสามารถใช้เพื่อรวบรวมข้อมูลการออกแบบสถาปัตยกรรมและรายละเอียดระดับ

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

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

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

ในข้อกำหนดที่ไม่ได้ใช้งาน:

ข้อกำหนดที่ไม่เกี่ยวกับการทำงานคือข้อกำหนดที่ระบุเกณฑ์ที่สามารถใช้ตัดสินการทำงานของระบบได้มากกว่าพฤติกรรมที่เฉพาะเจาะจง พวกเขาจะแตกต่างกับข้อกำหนดการทำงานที่กำหนดพฤติกรรมหรือฟังก์ชั่นที่เฉพาะเจาะจง แผนสำหรับการนำความต้องการของฟังก์ชันไปใช้นั้นมีรายละเอียดในการออกแบบระบบ แผนสำหรับการนำข้อกำหนดที่ไม่ได้ใช้งานไปใช้นั้นมีรายละเอียดในสถาปัตยกรรมระบบ

ความต้องการในการใช้งานในวงกว้างกำหนดสิ่งที่ระบบควรทำและข้อกำหนดที่ไม่เกี่ยวกับการทำงานกำหนดว่าระบบควรจะเป็นอย่างไร ... ข้อกำหนดที่ไม่สามารถใช้งานได้มักเรียกว่า "คุณสมบัติคุณภาพ" ของระบบ ข้อกำหนดอื่น ๆ สำหรับข้อกำหนดที่ไม่ใช่หน้าที่การใช้งานคือ "คุณภาพ", "เป้าหมายคุณภาพ", "คุณภาพของข้อกำหนดบริการ", "ข้อ จำกัด " และ "ข้อกำหนดที่ไม่ใช่พฤติกรรม"

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

สถาปัตยกรรมซอฟต์แวร์ที่มีสิทธิ์จะต้องมี 3 สิ่ง

ที่เปิดเผย

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

นี่คือความแตกต่างที่สำคัญ การออกแบบระบบควรถูก จำกัด โดยสถาปัตยกรรมระบบซึ่งในความเป็นจริงมันแยกจากกัน แต่เกี่ยวข้องกับสิ่งต่างๆ

หลักการและเหตุผล

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

ทำไมการตัดสินใจครั้งนี้จึงเกิดขึ้น? เราอธิบายว่าทำไมในส่วนเหตุผลและเชื่อมโยงคำอธิบายของเรากลับไปยังข้อกำหนดที่ไม่ได้ใช้งานเป้าหมายคุณภาพของแอตทริบิวต์หรือข้อกำหนดที่สำคัญทางสถาปัตยกรรม (เช่นงานจะต้องไม่ตรงกันและทำซ้ำได้การบำรุงรักษาเป็นแอตทริบิวต์คุณภาพไดรฟ์ที่ในกรณีที่งานล้มเหลวเป็นชุดที่งานสามารถเริ่มต้นใหม่ผ่านข้อความ MQ ระบบจะต้องมีการสูญเสียข้อความเป็นศูนย์ด้วยการสื่อสารแบบอะซิงโครนัส ฯลฯ .. )

ความเสี่ยง

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

(เช่นการตรวจสอบฝั่งเซิร์ฟเวอร์กำลังทำซ้ำในโค้ด Javascript ฝั่งไคลเอ็นต์นี่เป็นการละเมิดหลักการ DRY และสิ่งนี้เรียกใช้เพื่อตอบสนองต่อแอตทริบิวต์คุณภาพของการดูแลรักษาไม่มีข้อกำหนดที่ไม่เกี่ยวกับการใช้งาน ไม่มีเหตุผลสำหรับพฤติกรรมของระบบในปัจจุบัน)

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

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

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

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

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

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

ฉันอยากจะเขียนเอกสารสถาปัตยกรรมที่แบ่งออกเป็น 3 ส่วนหลัก ๆ

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

ส่วนที่สองควรจะอธิบายอย่างชัดเจนว่าสิ่งที่สถาปัตยกรรมจริงคือ สิ่งนี้จะช่วยให้นักพัฒนาซอฟต์แวร์ / ผู้อ่านใหม่ได้รับแนวคิดเกี่ยวกับสถานะการเล่นปัจจุบันและสิ่งที่พวกเขากำลังเผชิญหากพวกเขาดูซอฟต์แวร์ (และเอกสารอื่น ๆ ที่อาจเป็นไปได้) ส่วนนี้ควรระบุอย่างชัดเจนถึงความแตกต่างระหว่างสิ่งที่ตั้งใจและความเป็นจริงเพราะสิ่งนี้น่าจะเป็นไฮไลต์ที่ผิดปกติมากกับสถาปัตยกรรมดั้งเดิม (หวังว่าจะไม่มากเกินไป!) และพื้นที่ที่ทางลัด / แฮ็ก มีแรงกดดันในระดับสูงต่อทีมงาน dev) และไม่ได้ทำตามข้อกำหนดหรือซอฟต์แวร์ขอร้องให้ดู 'ไม่ดี' ที่ออกแบบมาเช่นบอบบางเปราะบางไม่มีเสถียรภาพพกพาไม่ได้

ในที่สุดฉันคิดว่าส่วนรายละเอียดคำแนะนำสำหรับสิ่งที่ต้องเกิดขึ้นตอนนี้ นี่ควรเป็นการเปลี่ยนแปลงสถาปัตยกรรม / การออกแบบและแผนงานสำหรับการเปลี่ยนแปลงซอฟต์แวร์ในปัจจุบันเพื่อให้วิสัยทัศน์ของคุณเป็นจริง

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