Wprowadzenie
Artykuł Architektura kodu aplikacji jako pierwszy etap tworzenia oprogramowania napisany w 2017 roku, kończyłem słowami:
Nie chodzi więc o to by podzielić oprogramowanie na “składowe, które łączą w sobie możliwość przechowywania danych oraz wykonywania operacji”. Chodzi o to by mechanizm, o dowiedzionej poprawności, zaimplementować w określonej wybranej technologii.
https://it-consulting.pl/2017/07/15/architektura-kodu-aplikacji-jako-pierwszy-etap-tworzenia-oprogramowania/
Dokumentowanie i dokumentacja w projektach inżynierii oprogramowania to temat wielu i sporów i nieporozumień. Jednak kluczowymi błędami są najczęściej:
- teza, że dokumentację tworzymy po zakończeniu prac,
- teza, że jest to “jedna dokumentacja”.
ad.1. Niestety to najgorsza forma, bo etap rozwiązywania problemu realizowany jest wprost z użyciem kodu (code first), czyli najkosztowniejszą metodą. Praktyka pokazuje, że zwinne projekty “code-first” owocują nawet 10krotnie niższa efektywnością.
ad.2. Jest to założenie, że nie ma granicy między środowiskiem aplikacji a aplikacją.
Obie formy są możliwe do realizacji, pytanie czy nie można inaczej i lepiej? Logikę się projektuje przed kodowaniem, infrastrukturę się dokumentuje po jej uruchomieniu.
Aplikacja i jej środowisko to dwa różne projekty
Od 2003 roku (publikacja opisu tak zwanej architektury heksagonalnej):
Powyższy diagram (dość często cytowany w literaturze, ) pokazuje ideę tego wzorca architektonicznego: separujemy realizację wymagań funkcjonalnych (aplikacja, obszar objęty czerwoną granicą) od środowiska w jakim ona sie wykonuje (obszar poza czerwona granicą). Dokładnie tak samo jak np. kod aplikacji Edytor Tekstu od kodu MS Windows. Są to zupełnie dwa różne produkty, a jedyne co je łączy to to to że, edytor tekstu korzysta z usług systemu operacyjnego przez jego API (porty). Identycznie tworzymy każde inne oprogramowanie: aplikacja osobno, środowisko osobno.
Dokumentacja czyli co to jest i ile zajmuje czasu
Każdy projekt inżynierski ma kilka faz, są to: określenie problemu i wskazanie rozwiązania, określenie wymagań wobec rozwiązania, zaprojektowanie rozwiązania, implementacja i wdrożenie rozwiązania.
Tak więc mamy:
- Dokumentację działania organizacji czyli udokumentowany jej biznesowy model działania. W nomenklaturze OMG jest to Computation Independent Model:
- mapy procesów biznesowych (BPMN),
- słownik pojęci i reguły biznesowe (SBVR)
- procedury (RACI, CRUD, listy kontrolne)
- szablony dokumentów (diagram struktur złożonych UML, inne formy graficzne)
- Specyfikacja wymagań, forma zależna od preferencji:
- wymagania funkcjonalne i poza-funkcjonalne,
- user story,
- inne.
- Dokumentacja-projekt HLD, tu “z lotu ptaka” pokazujemy projekt realizacji funkcjonalności i strategię utrzymania i rozwoju aplikacji (notacja UML/SysML):
- Lista usług systemu (przypadki użycia UML)
- Architektura HLD (diagram komponentów UML)
- Specyfikacje i scenariusze przypadków użycia na poziomie HLD (diagramy sekwencji UML, diagramy aktywności UML)
- Dokumentacja-projekt realizacji wymagań pozafunkcjonalnych czyli platformy systemowej i środowiska aplikacji (notacja UML/SysML, architektura C4, inne formy dokumentacji dostarczonej prze producenta platformy).
- Dokumentacja-projekt LLD, realizacji określonych komponentów wskazanych na modelu HLD:
- Architektura LLD (diagram klas UML),
- Specyfikacje i scenariusze operacji komponentu na poziomie LLD (diagramy sekwencji UML, diagramy aktywności UML)
- Implementacja komponentu
Praktyka autora tego tekstu i wielu innych autorów podobnych publikacji , pokazuje, że:
- etap analizy biznesowej i spisanie wymagań to ok. 3 miesiące,
- opracowanie architektury HLD to maksymalnie ok. 1 tydzień,
- każdy komponent LLD to nie raz nawet tylko kilka godzin rysowania w UML,
- implementacja tych kolejnych komponentów w zbudowanym już środowisku, to dni a rzadziej tygodnie.
Etapy te zostały ujęte w tak zwany V-model , z perspektywy projektów inżynierii oprogramowania, zobrazowany poniżej:
Analityk-projektant realizuje elementy analizy i projektowania, deweloper to punkt 4. oraz kolejne realizacje pkt. 6. Projekt ma trzy ramowe etapy:
- Analiza biznesowa: analityk-projektant.
- Specyfikacja Wymagań: analityk-projektant;
- Projektowanie rozwiązania i iteracyjno-przyrostowe wytwarzanie go: w petli SDLC analityk-projektant + deweloper .
Jeżeli projekt jest komponentowy, wtedy V-model przybiera postać jak poniżej:
Tak więc z perspektywy dewelopera, użyteczne oprogramowanie powstaje już po niecałych 2 tygodniach. To wynik niemalże nie do osiągniecia przy pracy bez analiz i projektu od razy w kodzie na bazie user story. Ważne jest także to, że zyskujemy tak dokumentację zmian w całym cyklu życia projektu (ADR, ang. Architecture Decision Records, ) co jest bardzo ważne z perspektywy zarządzania zmianą.
Podsumowanie
Metody zwane agile, spopularyzowały podejście zwane code-first. Niestety czas pokazał, że w dłuższej perspektywie są najmniej efektywne:
Badanie wykazało 268% wyższy wskaźnik niepowodzeń w projektach oprogramowania Agile.
https://www.theregister.com/2024/06/05/agile_failure_rates/
Efektywność uzyskujemy przemyślaną architekturą i potem jej sprawną implementacją (np. językami skryptowymi). Doświadczony projektant, w rozwiązywaniu problemów dziedzinowych, jest nawet dziesięciokrotnie efektywniejszy niż koder pracujący od razu z kodem z tradycyjnymi frameworkami takimi jak JavaEE/Spring czy bardzo podobnym .NET Framework.
W kwestii same organizacji dokumentacji co do zasady: dokumentujemy od ogółu do szczegółu, oraz zawsze osobno logikę i osobno infrastrukturę.
Bardzo ważne: logikę się projektuje przed kodowaniem, infrastrukturę się dokumentuje po jej uruchomieniu .
Prowadzę warsztaty dla zespołów analityków, projektantów i deweloperów, na których prezentuję, omawiam i wyjaśniam opisane wyżej i dobrze znane na świecie metody projektowania i dokumentowania (wykup warsztaty dla zespołu albo umów sie na indywidualne konsultacje). Od niedawna oferuje "gotowce" jako wzory i przykłady w Sklepiku.
