Czy istnieje standard dokumentowania architektury wysokiego poziomu programu?

10

Jestem programistą-amatorem, a wszystkie moje dotychczasowe programy były na tyle proste, że można je udokumentować w kodzie. Podczas czytania kodu było jasne, co robię w takim przypadku (moim standardowym testem było przyjrzenie się kodowi 6 miesięcy później i zrozumienie wszystkiego przy pierwszym czytaniu - i mam krótki zakres pamięci).

Mam teraz do czynienia z programem, który przerasta moje możliwości zapamiętywania różnych interakcji między nimi

  • sam kod
  • indeksy w bazie danych
  • interakcje między różnymi modułami (kod podstawowy „roboczy” i „biblioteka”)

Moja obecna dokumentacja to biała tablica, na której mam wszelkiego rodzaju pola i strzałki, które wskazują na kod, indeksy baz danych, wykonywane działania, zmiany stanu itp. Tylko dla odniesienia fragment bałaganu:

wprowadź opis zdjęcia tutaj

Moje pytanie brzmi, czy istnieje standardowy lub nazwany zestaw najlepszych praktyk (nazwanych w tym sensie, że jest to zestaw praktyk, które zostały pogrupowane pod konkretną nazwą) do dokumentacji bardziej złożonych produktów.

Jakich słów kluczowych powinienem szukać (ogólne próby „dokumentowania standardów architektury oprogramowania” i podobne odmiany zwykle prowadziły do ​​oprogramowania dla przepływów pracy lub systemów CAD architektury budynku).

Spodziewam się również, że mogą nie istnieć ogólne najlepsze praktyki dotyczące opisów na wysokim poziomie i że każdy zbuduje własną filozofię.

WoJ
źródło
um UML i zwykle zwykły stary tekst
jk.
Jeśli umiesz czytać po niemiecku, spójrz na arc42.de/template/index.html Pokazują one kilka wskazówek dla dokumentacji architektury oprogramowania.
Bernhard Hiller,
8
„Nie zawracanie sobie tym głowy” jest prawdopodobnie najbliższe standardowi.
whatsisname

Odpowiedzi:

13

Nie ma jednego standardu, który wszyscy przestrzegają. Projekty oprogramowania mogą się znacznie różnić (pomyśl: helloworld.py vs. kod w promie kosmicznym).

Jedną z bardzo powszechnych metod jest użycie modelu 4 + 1 . Zamiast próbować wcisnąć wszystko w jeden styl dokumentu, ta metodologia dzieli projekt na pięć składników:

  • Development widok
  • Logical widok
  • Fizyczny widok
  • Sposób widok
  • Scenariusze

Różne widoki opisują produkt z czterech różnych perspektyw. Scenariusze przedstawiają przypadki użycia i opisują interakcję innych widoków.

Uwaga: jest to model koncepcyjny i nie jest powiązany z żadnym konkretnym narzędziem.

Możesz przeczytać więcej tutaj:

  1. Model widoku architektonicznego 4 + 1 (wikipedia)
  2. Plany architektoniczne - model architektury oprogramowania „4 + 1” (dokument IEEE - pdf)
Bryan Oakley
źródło
To bardzo dobre podejście, dzięki. Cofając się, można by pomyśleć, że jest to dość oczywiste, ale bardzo pomaga rozdzielić różne elementy 4 + 1, które wszystkie miałem na jednym wykresie.
WoJ,
4

IMHO UML nie jest narzędziem, które działa dobrze do dokumentowania architektury oprogramowania w świecie rzeczywistym. Diagramy klas są użyteczne, ale używają poziomu abstrakcji, który jest często zbyt niski do tego celu. Diagramy przypadków użycia są zwykle zbyt „na wysokim poziomie” i nie uwzględniają niektórych aspektów. Inne typy diagramów UML mają podobne problemy (Szczerze mówiąc, diagramy pakietów, diagramy wdrażania, diagramy komponentów mogą dokumentować pewne aspekty architektoniczne, ale osobiście nigdy nie uważałem ich za bardzo przydatne).

Jeśli szukasz sprawnego, pragmatycznego sposobu dokumentowania architektur wysokiego poziomu, sugeruję zapoznanie się ze schematami przepływu danych . Są łatwe do zrozumienia i mają tę zaletę, że można je skalować do różnych poziomów abstrakcji. Uważam je za najbardziej przydatne do dokumentowania różnego rodzaju systemów. Szkoda, że ​​nie znaleźli drogi do UML, ale mimo to znajdziesz wiele narzędzi - nawet darmowych, takich jak Dia lub DrawIO - do tworzenia tych diagramów.

Na marginesie, dlaczego potrzebujesz „indeksów w bazie danych” w dokumentacji wysokiego poziomu? Myślę, że są one szczegółami implementacyjnymi twojego (relacyjnego?) Modelu danych, a jeśli je dodasz lub nie, to - według mojego doświadczenia - bardziej kwestia wydajności i optymalizacji.

Doktor Brown
źródło
Schematy pakietów? Diagramy wdrażania? Diagramy komponentów?
Nick Keighley
3
Szczerze mówiąc, kilka pudeł ze strzałkami może zdziałać cuda, przekazując szereg funkcji projektowych. Wydaje mi się, że diagramy komponentów należą do tej kategorii, ale moi klienci rozumieją przepływ danych za pomocą pól reprezentujących główne bity. Zgadzam się z Doc Brown. Formalność UML pomija znak w zamierzonym celu.
Berin Loritsch
@NickKeighley: zobacz moją edycję.
Dok. Brown
@BerinLoritsch: IMHO „kilka pól ze strzałkami” charakteryzuje typy diagramów wspomniane przez Nicka Keighleya. Jednak diagramy przepływu danych wyraźnie rozróżniają formalnie dane lub grupy / klastry danych oraz procesy lub komponenty, które przesyłają lub przekształcają te dane. To nic, co mogę łatwo wyrazić za pomocą dowolnego z diagramów UML.
Doc Brown
1
Muszę przyznać, że czasami uciekam się do diagramów przepływu danych - szczególnie tych, które pozwalają sklepom. W rzeczywistości schemat najwyższego poziomu, który opisuje nasz system, jest zasadniczo DFD. Nadal uważam diagramy klas i pakiet za przydatne w pewnym stopniu. Nie zwracam uwagi na „formalne” części UML.
Nick Keighley,
0

Unified Modeling Language (UML) to uniwersalny, rozwojowy język modelowania w dziedzinie inżynierii oprogramowania, który ma na celu zapewnienie standardowego sposobu wizualizacji projektu systemu.


źródło
Formalną specyfikację można znaleźć na omg.org/spec/UML/2.5, ale w sieci jest wiele bardziej przyjaznych samouczków.
Simon B,
2
Ta odpowiedź to tylko część pytania, UML jest zdecydowanie odpowiednim narzędziem do modelowania, ale sama w sobie nie stanowi pełnej dokumentacji
Walfrat,
3
Czy ktoś bardzo często używa UML?
Panzercrisis,
doodling. inżynieria odwrotna.
Nick Keighley,
1
@Walfrat. czy to jest Naprawdę? Mam wątpliwości.
Doc Brown,
-3

Myślę, że kiedyś robiliśmy to lepiej. Wydawało się, że UML wylewa dziecko z kąpielą. Zapewniając zunifikowany język modelowania, zniesiono rozróżnienie między architekturą a implementacją. Lub jeśli nie miało to na celu, wydaje się, że miało to skutek.

Widziałem niektóre modele UML potworów i, szczerze mówiąc, nie robią dla mnie niczego, czego nie mógłby zrobić kod, i robią to lepiej.

Nick Keighley
źródło
3
nie odpowiada na pytanie, prawdopodobnie lepiej jako komentarz do odpowiedzi SuperGirl.
Newtopian
1
Odpowiada na pytanie. Twierdzę, że odpowiedź na pytanie brzmi bardziej „nie” niż kiedyś.
Nick Keighley,