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:
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ę.
Odpowiedzi:
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:
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:
źródło
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.
źródło
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
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.
źródło