Kontekst: Ja i moi współpracownicy piszemy artykuł do czasopisma akademickiego. W trakcie naszych badań napisaliśmy program symulacyjny w Javie. Chcemy, aby program symulacji był swobodnie dostępny dla innych. Zdecydowaliśmy się na hosting kodu w repozytorium GitHub. Aby ułatwić innym korzystanie, chcemy napisać dobrą dokumentację dla naszego programu, w tym:

• Javadocs dla każdej klasy i metody
• Jak korzystać z kodu
• Opis struktury wysokiego poziomu kodu

Moje pytanie na wysokim poziomie brzmi: czy możesz podać dobry przykład słów i diagramów, których można użyć do opisania struktury wysokiego poziomu programu? Obejmuje to następujące pytania częściowe:

1. Jak pokazać, jakie klasy są zawarte w poszczególnych pakietach?
2. Jak pokazujemy, które pakiety zależą od innych pakietów?
3. Jak pokazujemy, jak obiekty / klasy w programie współpracują ze sobą?
4. Próbowaliśmy używać zasad projektowania opartych na domenie przy projektowaniu mojego kodu. Jak pokazujemy zgodność między obiektami w domenie a konkretnymi plikami kodu źródłowego kodującymi te obiekty? (Zobacz mój opis „wszechobecnego języka” projektu poniżej.)

Co zrobiłem do tej pory

Wszechobecny język

Umieszczamy opis kodu „wszechobecnego języka” w pliku ubiquitous-language.md, treść poniżej.

Celem tego projektu jest zbadanie, jak dobrze funkcjonuje polityka uzupełniania zapasów w prostym łańcuchu dostaw z jednym zakładem, przy różnych modelach czasu realizacji, opóźnieniach raportów i modelach popytu.

W każdym okresie występują następujące zdarzenia:

1. Jeśli przesyłka ma dotrzeć do obiektu w bieżącym okresie, poziom zapasów w obiekcie zwiększa się o X jednostek.
2. Jeśli harmonogram wskazuje, że bieżący okres jest okresem sprawozdawczym, wówczas zakład przekazuje raport do dostawcy . Dostawca może otrzymać raport natychmiast lub z opóźnieniem kilku tygodni, określonym przez harmonogram .
3. Jeśli dostawca otrzymał raport , a następnie w oparciu o zasady uzupełnienia , obliczy ilość uzupełnienia X jednostek. Transportu jednostek X produktu będzie przybyć od ołowiu czasie okresów l.
4. Klienci przybywają do obiektu i żądają X jednostek produktu. Wszelkie niezaspokojone zapotrzebowanie zostanie utracone.

Struktura kodu źródłowego

W pliku umieszczamy niepełny opis „wysokiego poziomu” kodu structure.md, treść poniżej.

Struktura poziomu pakietu

Na najwyższym poziomie kod źródłowy jest podzielony na trzy pakiety

• com.gly.sfs Główna klasa z tą mainmetodą znajduje się w tym pakiecie.
• com.gly.sfs.model Klasy modeli domen znajdują się w tym pakiecie.
• com.gly.sfs.util Klasy pomocnicze znajdują się w tym pakiecie.

Zwykle używasz UML do opisanego celu. UML dzieli się zasadniczo na dwa typy diagramów: strukturalny i behawioralny.

Diagramy strukturalne obejmują: skład, wdrożenie, pakiet, klasę, obiekt i komponent. Diagramy behawioralne obejmują: sekwencję, automat stanów, komunikację, przypadek użycia, aktywność i przegląd interakcji.

W zależności od tego, co próbujesz przekazać, wybierasz kilka z tych diagramów, które najlepiej przedstawiają wszystko, co próbujesz przekazać, a tym samym pozwalasz rozmowie „przejść na wyższy poziom”. Zamiast mówić o metodach, parametrach i kodzie, mówisz o sekwencji interakcji, zależnościach klas statycznych lub dowolnych diagramach, które chcesz utworzyć.

Dołączyłem przykład diagramu sekwencji (jeden ze schematów zachowania). Osobiście podoba mi się schemat sekwencji, ponieważ znajduje się on w samym środku procesu tworzenia artefaktu - w przybliżeniu tyle samo diagramów zależy od niego, jak oczekuje się na wejściu. Uważam, że diagramy wejściowe są zazwyczaj „rozumiane”, a schemat sekwencji już implikuje ich istnienie. Czasami jednak wykonuję zarówno diagramy klas statycznych, jak i diagramy sekwencji (jeden schemat strukturalny i jeden schemat behawioralny).

http://omarfrancisco.com/wp-content/uploads/2011/07/sequsequiagram.png

Nigdy w życiu nie widziałem tego schematu, ale mogę powiedzieć wiele rzeczy o tym systemie. Istnieją cztery główne komponenty (rzeczowniki w systemie - zazwyczaj klasy): Widok, Kontroler, Proxy danych i Dostawca danych. Strzałki to „zachowania” lub wywołania metod. Schemat sekwencji jest w zasadzie dobry do pokazania jednej ważnej interakcji między wiązką składników. Masz jeden schemat sekwencji dla każdego ważnego przepływu przez twój system. Mogę powiedzieć z tego konkretnego diagramu, że „Controller” ujawnia metodę o nazwie „phoneIsComplete ()”, która z kolei zależy od metody „lookupPhone ()” DataProviderProxy, która z kolei zależy od metody „lookupPhone ()” DataProvider.

Teraz możesz jęczeć i pomyśleć „uggg ... to nie daje mi dużego obrazu systemu - to tylko indywidualne interakcje za pośrednictwem systemu”. W zależności od złożoności systemu może to być uzasadniona obawa (proste systemy z pewnością mogą sobie poradzić z kolekcją diagramów sekwencji). Przechodzimy więc do schematów strukturalnych i patrzymy na coś w rodzaju schematu klasy statycznej:

http://www.f5systems.in/apnashoppe/education//img/chapters/uml_class_diagram.jpg

Diagramy klas pomagają nam zrozumieć dwie ważne rzeczy: liczność i typy relacji klasowych. Klasy mogą być powiązane ze sobą na różne sposoby: asocjacja, agregacja i skład. Technicznie rzecz biorąc, istnieje różnica między „statycznymi relacjami klas” a „relacjami instancji”. Jednak w praktyce linie te są rozmyte. Główną różnicą jest to, że relacje klas statycznych zwykle nie obejmują liczności. Spójrzmy na powyższy przykład i zobaczmy, co możemy zobaczyć. Po pierwsze, widzimy, że „Specjalny porządek” i „Normalny porządek” są podtypami „Rozkazów” (dziedziczenie). Widzimy również, że jeden Klient ma N Zamówień (które mogą być „Zamówieniami zwykłymi”, „Zamówieniami” lub „Zamówieniami specjalnymi”) - obiekt Klienta nie „ naprawdę wiem. Możemy również zobaczyć szereg metod (w dolnej połowie każdego pola klasy) i właściwości (górna połowa każdego pola klasy).

Mógłbym długo mówić o diagramach UML, ale to są podstawy. Mam nadzieję, że to pomaga.

TLDR; Wybierz jeden behawioralny i jeden strukturalny diagram UML, naucz się go tworzyć, a osiągniesz to, co próbujesz osiągnąć.

Jeśli masz trudności z opisaniem takich rzeczy, jak struktura wysokiego poziomu programu i jak dobrze działają klasy, rozważ następującą maksymę:

A picture is worth a thousand words.

Sposób malowania obrazu na temat kodu polega na podawaniu przykładów kodu. Wiele z nich. W ten sposób tworzysz nowego klienta (kod). W ten sposób realizujesz zamówienie (kod). To nie tylko daje konsumentowi twojego kodu miejsce do rozpoczęcia, ale ilustruje, w jaki sposób wszystkie obiekty łączą się ze sobą i wchodzą w interakcje. Gdybym używał twojego kodu, największą korzyścią, jaką możesz mi zrobić, jest dostarczenie wielu próbek kodu.

Malowanie obrazu dla użytkownika końcowego polega na udostępnianiu zrzutów ekranu. Wiele z nich. Zrzut ekranu po zrzucie ekranu, który ilustruje, że jeśli chcesz wykonać to zadanie, to najpierw robisz, to robisz później itp.

UML, choć często używany do modelowania oprogramowania przed jego utworzeniem, może być przydatny. Istnieje kilka różnych diagramów ilustrujących przypadki użycia, interakcje klas itp. Itp. Więcej informacji na ten temat można znaleźć tutaj .

Uważam https://www.websequsequiagrams.com/ za niezwykle przydatne narzędzie do opisywania interakcji między komponentami w aplikacji lub między usługami w aplikacji rozproszonej. To po prostu znacznie ułatwia proces tworzenia i utrzymywania diagramów sekwencji UML.

Zaletą jest to, że jeśli weźmiesz pod uwagę każdą linię życia jako interfejs lub klasę w twojej aplikacji (zazwyczaj modeluję tylko dużych graczy), to każda linia płynąca do tej klasy reprezentuje metodę, którą musisz obsługiwać.

Ponadto istnieją pewne opcje pobierania, aby uzyskać obraz. Istnieje również kilka łatwych sposobów osadzenia diagramu w wiki. Jest to więc świetne narzędzie komunikacyjne do opisu interakcji między komponentami lub usługami w systemie, a także do komunikacji z zespołem.