มีมาตรฐานสำหรับการทำเอกสารสถาปัตยกรรมระดับสูงของโปรแกรมหรือไม่?

10

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

ตอนนี้ฉันกำลังเผชิญกับโปรแกรมที่เกินความสามารถของฉันในการจดจำปฏิสัมพันธ์ต่าง ๆ ระหว่าง

รหัสเอง
ดัชนีในฐานข้อมูล
การโต้ตอบระหว่างโมดูลต่าง ๆ ("ผู้ปฏิบัติงาน" รหัสหลักและคน "ห้องสมุด")

เอกสารปัจจุบันของฉันคือไวท์บอร์ดที่ฉันมีกล่องและลูกศรทุกชนิดซึ่งชี้ไปที่รหัสดัชนีฐานข้อมูลการดำเนินการการเปลี่ยนแปลงสถานะ ฯลฯ เพียงเพื่อการอ้างอิงส่วนของระเบียบ:

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

ฉันควรมองหาคำหลักใด (ความพยายามทั่วไปที่ "มาตรฐานสถาปัตยกรรมซอฟต์แวร์เอกสาร" และรูปแบบที่คล้ายคลึงกันมักนำไปสู่ซอฟต์แวร์สำหรับเวิร์กโฟลว์หรือระบบ CAD สถาปัตยกรรมสถาปัตยกรรม)

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

architecture documentation

— WoJ
แหล่งที่มา

อืมม UML และข้อความเก่าธรรมดาบางอย่าง

— jk

หากคุณสามารถอ่านภาษาเยอรมันลองดูที่arc42.de/template/index.htmlพวกเขาจะแสดงเส้นบอกแนวสำหรับสถาปัตยกรรมซอฟต์แวร์เอกสาร

— Bernhard Hiller

8

"ไม่รำคาญที่จะทำเลย" น่าจะใกล้เคียงที่สุดกับมาตรฐาน

— whatsisname

13

ไม่มีมาตรฐานเดียวที่ทุกคนปฏิบัติตาม โครงการซอฟต์แวร์อาจแตกต่างกันอย่างมาก (คิดว่า: helloworld.py เทียบกับรหัสในกระสวยอวกาศ)

วิธีการหนึ่งที่พบบ่อยมากคือการใช้4 + 1 รุ่น แทนที่จะพยายามยัดทุกอย่างลงในเอกสารรูปแบบเดียววิธีการนี้แบ่งการออกแบบออกเป็นห้าองค์ประกอบ:

พัฒนามุมมอง
ตรรกะมุมมอง
ทางกายภาพมุมมอง
กระบวนการมุมมอง
สถานการณ์

มุมมองที่หลากหลายอธิบายผลิตภัณฑ์จากมุมมองที่แตกต่างกันสี่แบบ สถานการณ์เป็นกรณีที่มีการใช้งานจริงและอธิบายการโต้ตอบของมุมมองอื่น ๆ

หมายเหตุ: นี่เป็นรูปแบบแนวคิดและไม่เชื่อมโยงกับเครื่องมือเฉพาะใด ๆ

คุณสามารถอ่านเพิ่มเติมได้ที่นี่:

โมเดลมุมมองสถาปัตยกรรม 4 + 1 (วิกิพีเดีย)
พิมพ์เขียวทางสถาปัตยกรรม - มุมมอง“ 4 + 1” ดูรุ่นของสถาปัตยกรรมซอฟต์แวร์ (กระดาษ IEEE - pdf)

— ไบรอัน Oakley
แหล่งที่มา

นี่เป็นวิธีการที่ดีมากขอบคุณ เมื่อย้อนกลับไปหนึ่งอาจคิดว่ามันชัดเจนมาก แต่มันช่วยได้มากในการตัดการเชื่อมต่อ 4 + 1 ชิ้นต่าง ๆ ที่ฉันมีในกราฟเดียว

— WoJ

4

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

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

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

— หมอบราวน์
แหล่งที่มา

แพคเกจไดอะแกรม? ไดอะแกรมการปรับใช้งานหรือไม่ ส่วนประกอบไดอะแกรม?

— Nick Keighley

3

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

— Berin Loritsch

@NickKeighley: ดูการแก้ไขของฉัน

— Doc Brown

@BerinLoritsch: IMHO "พวงของกล่องที่มีลูกศร" อธิบายถึงประเภทไดอะแกรมที่ Nick Keighley พูดถึง อย่างไรก็ตามแผนภาพการไหลของข้อมูลทำให้ความแตกต่างอย่างเป็นทางการชัดเจนระหว่างข้อมูลหรือกลุ่ม / กลุ่มข้อมูลและกระบวนการหรือส่วนประกอบที่ถ่ายโอนหรือแปลงข้อมูลเหล่านี้ นั่นคือสิ่งที่ฉันสามารถแสดงกับไดอะแกรม UML ใด ๆ ได้อย่างง่ายดาย

— Doc Brown

1

ฉันต้องยอมรับว่าบางครั้งฉันก็หันไปใช้แผนภาพกระแสข้อมูล - โดยเฉพาะอย่างยิ่งที่อนุญาตร้านค้า อันที่จริงไดอะแกรมระดับบนสุดที่อธิบายระบบของเราคือ DFD ฉันยังคงพบว่าคลาสไดอะแกรมและแพ็คเกจมีประโยชน์ในระดับหนึ่ง ฉันไม่สนใจส่วน "ทางการ" ของ UML มากนัก

— Nick Keighley

0

Unified Modeling Language (UML) เป็นภาษาที่มีวัตถุประสงค์ทั่วไป, การพัฒนา, การสร้างแบบจำลองในสาขาวิศวกรรมซอฟต์แวร์ที่มีจุดประสงค์เพื่อให้วิธีมาตรฐานในการแสดงภาพการออกแบบของระบบ

ข้อมูลจำเพาะอย่างเป็นทางการสามารถพบได้ที่omg.org/spec/UML/2.5แต่มีบทเรียนมากมายที่เป็นมิตรบนเว็บ

— Simon B

2

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

— Walfrat

3

มีใครใช้ UML บ่อยมากไหม

— Panzercrisis

doodling วิศวกรรมย้อนกลับ

— Nick Keighley

1

@Walfrat ใช่ไหม? จริงๆ? ฉันมีข้อสงสัย

— Doc Brown

-3

ฉันคิดว่าเราเคยทำดีกว่า UML ดูเหมือนจะโยนลูกออกไปด้วยน้ำอาบ ในการให้บริการ Unified Modeling Language นั้นได้ยกเลิกความแตกต่างระหว่างสถาปัตยกรรมและการใช้งาน หรือถ้ามันไม่ได้ตั้งใจที่จะดูเหมือนจะมีผล

ฉันเห็นรูปแบบ UML ของสัตว์ประหลาดและพวกเขาไม่ทำอะไรเลยสำหรับฉันว่ารหัสไม่สามารถทำได้และทำได้ดีกว่า

— Nick Keighley
แหล่งที่มา

3

ไม่ตอบคำถามน่าจะดีกว่าเป็นความคิดเห็นในคำตอบของ SuperGirl

— Newtopian

1

มันตอบคำถาม ฉันโต้เถียงว่าคำตอบของคำถามนั้นมากกว่า "ไม่" มากกว่าที่เคยเป็น

— Nick Keighley