8.02.20226 min

Nick TuneTechnical Leader and Socio-Technical Architect

Co zmienia samodokumentująca się architektura?

Poznaj perspektywy wykorzystania samodokumentującej się architektury i narzędzia, które przybliżają nas do tego celu.

Co zmienia samodokumentująca się architektura?

Jedną z najbardziej czasochłonnych rzeczy podczas tworzenia oprogramowania jest zrozumienie, jak działa system. Problem ten może być coraz poważniejszy. Systemy stają się coraz bardziej złożone, ale nasza zdolność do ich rozumienia nie wydaje się rosnąć w tym samym tempie.

Wraz z ciągłym rozwojem systemów oprogramowania, złożoność staje się coraz poważniejsza, a my nie do końca zdajemy sobie z tego sprawę. Nikt nie ma zamiaru tworzyć Wielkiej Kuli Błota, ale wiele baz kodu kończy w ten sposób z powodu skumulowanego efektu tysięcy małych zmian, które wprowadzamy.

Złożone systemy są trudniejsze do nauczenia i ciężej jest nowym pracownikom być w nich produktywnym. Słyszałem, jak wielu tech leaderów twierdzi, że rozsądnie jest czekać, aż nowy pracownik poświęci do 6 miesięcy na poznanie kodu, domeny i architektury, zanim stanie się w pełni produktywny.

Wierzę, że samodokumentująca się architektura radykalnie zmniejszyłaby jeden z większych kosztów w rozwoju oprogramowania. Wszyscy mówią o samodokumentującym się kodzie, ale to tylko mała część czegoś zupełnie większego.


Dlaczego nie wykorzystać samodokumenującej się architektury?

Baza kodów to coś więcej niż tylko pliki tekstowe. To baza informacji domenowej, biznesowej i architektonicznej. Powinno być tak, że klikamy kilka przycisków i uzyskujemy w 100% dokładne wizualizacje modelu domeny, procesów biznesowych i architektury.

Samodokumentująca się architektura zredukowałaby krzywą uczenia się, uwypukliłaby złe wybory projektowe i tym samym pomogła w wyborze lepszych rozwiązań. To z kolei pomogłoby nam zobaczyć złożoność, którą dodajemy do „bigger picture”, gdy wprowadzamy zmiany w mniejszych elementach, jak również utrzymać tę złożoność na niższym poziomie. Uchroniłoby nas to przed niechlujnymi diagramami narysowanymi na białej tablicy, które wyjaśniają błędne myślenie jednej osoby twierdzącej, że system działa.


Przyśpieszenie krzywej uczenia się

Samodokumentujący się kod pomaga nam szybko dowiedzieć się, co robi dana metoda, czy kilka klas. Jednak samo dokumentowanie się kodu nie uwypukla całościowego obrazu: architektury, domeny i procesów biznesowych.

Korzyści płynące z samodzielnego dokumentowania się architektury wykraczają daleko poza zakres wdrażania nowych użytkowników. Dzięki skróconej krzywej uczenia każdy może lepiej zrozumieć system i wnieść większy wkład.

Jednym z powodów, dla których mamy długo działające zespoły, są koszty nauki nowej bazy kodu i domeny. Gdyby koszty te zostały zredukowane, mogłoby się zmienić całe nasze podejście do organizowania zespołów, umożliwiając tym samym większą płynność organizacyjną.


Poprawa projektu systemu

Ponieważ oprogramowanie stopniowo ewoluuje w sposób ciągły, poszczególne decyzje mogą wydawać się sensowne w oderwaniu od kontekstu, ale z perspektywy architektonicznej zmiany, te mogą dodać niepotrzebnej złożoności do systemu.

Dzięki samodokumentującej się architekturze każdy, kto wprowadza zmiany w systemie, może z łatwością powiększyć obraz i szerzej rozważyć następstwa zmian.

Jednym z powodów, dla którego używam Bounded Context Canvas jest to, że wizualizuje on wszystkie kluczowe decyzje projektowe dla poszczególnej usługi. Problemy z niespójnym nazewnictwem, słabo zdefiniowanymi granicami lub ściśle powiązanymi interfejsami publicznymi rzucają się w oczy. Kiedy te decyzje są podejmowane w oderwaniu od siebie, wydają się być w porządku, ale dopiero gdy są rozpatrywane w szerszym kontekście, ogólny projekt okazuje się być poniżej optymalnego poziomu.

Niestety, ładowanie do bazy danych canvas jest procesem ręcznym. Uważam, że dostęp do Bounded Context Canvas powinien być za darmo. Informacje te znajdują się w naszych systemach, więc powinny być łatwe do wyodrębnienia. W ramach naszego procesu developmentu moglibyśmy wtedy w szerszym świetle analizować każdą małą zmianę, którą wprowadzamy.


Żywa dokumentacja

Koncepcja samo dokumentującej się architektury znajduje się w przestrzeni, którą Cyrille Martraire nazywa żywą dokumentacją. Gdy system ewoluuje, dokumentacja ewoluuje wraz z nim, jest żywa.

Cyrille przedstawia w książce kilka sposobów, jakie dokumentacja może odegrać znaczącą rolę w poprawie naszej zdolności do lepszego zrozumienia systemów. Nie tylko ich aktualnego stanu, ale także uzasadnienia decyzji i dodatkowych informacji o domenie, które nie mogą być łatwo ujęte w kodzie.

Czytając tę książkę, zaczynasz widzieć, jak może wyglądać przyszłość rozwoju oprogramowania. Będzie to w mniejszym stopniu polegało na tym, że programiści biorą wymagania i wciskają je w niechlujną bazę kodu. W praktyce raczej na bogatym w informacje doświadczeniu, w którym twórcy oprogramowania będą rozumieli kontekst biznesowy, w jakim działa system i historię zmian w systemie.

Mam nadzieję, że ta książka zainspiruje całe pokolenia programistów i architektów, i pozwoli im rozwiązywać naprawdę trudne i wartościowe problemy związane z developmentem.


Nowe prymitywy

Jednym z problemów, które napotkałem w książce Cyrille’a jest to, że elementy składowe nie są jeszcze do końca dopracowane. Niektóre z informacji o domenie i architekturze, na których nam zależy, są trudne do wyodrębnienia z bazy kodu.

W Domain-Driven Design, koncepcje domeny są reprezentowane za pomocą pojęć takich jak zdarzenia (Domain Event), encje (entities), agregaty (Aggregates) i policy. W większości języków programowania wszystkie te pojęcia są przedstawione za pomocą klas.

Jak możemy zbudować narzędzia, które mogą automatycznie wizualizować nasz model domeny, jeśli jedyne co posiadamy to klasy do wyodrębnienia z kodu? Możemy spojrzeć na nazwy tych klas lub spróbować wywnioskować ich zachowanie. W książce Cyrille wykorzystuje adnotacje lub interfejsy znaczników.

Nie mam nic przeciwko adnotacjom i interfejsom znaczników, jeśli tylko umożliwiają one samo dokumentującą się architekturę. Nie jest to jednak optymalne doświadczenie dla programistów i może być podatne na błędy. Wymagane są tutaj rygor i dyscyplina.

A gdybyśmy zamiast tego wszyscy zgodzili się na pewne konwencje budowania architektury lub modelu domeny? Być może staną się one natywnymi konceptami w przyszłych językach programowania. Otrzymamy wtedy samodokumentującą się architekturę za darmo, ponieważ narzędzia mogą łatwo wyodrębnić koncepcje domeny z bazy kodu.

Wiem, że standardy będą odrzucane i może minąć kilka lat, zanim do tego wszystkiego dojdzie. Jednak korzyści są tak duże, że wydaje się to nieuniknione. W miarę jak języki programowania odsuwają od siebie coraz więcej przypadkowej złożoności, widzę, że otwiera się dla nich przestrzeń, w której będą mogły uwzględnić prymitywy domenowe wyższego poziomu.


Istniejące narzędzia

A co z narzędziami dostępnymi obecnie w przestrzeni samodokumentującej się architektury? Czym powinniśmy się ekscytować?

Structurizr stworzony przez Simona Browna jest jednym z narzędzi, które obserwuję z zainteresowaniem. Dostarcza język/DSL do opisywania koncepcji architektonicznych przy użyciu nomenklatury C4. Przypomina to w efekcie dodawanie adnotacji lub interfejsów znaczników, jednak identyfikacja konceptów w kodzie nadal wymaga wysiłku ze strony programistów.

Uważam, że przyszłość Structurizr jest niezwykle interesująca. Co, jeśli istnieje sposób, aby wbudować Structurizr we frameworki i platformy tak, abyśmy otrzymali samo dokumentującą się architekturę za darmo? Spoiler: Wiem już o podjętych wysiłkach w tym kierunku.

Innym narzędziem, na które zwracam szczególną uwagę jest Contexture stworzony przez Softwarepark. Contexture różni się od Structurizr tym, że skupia się bardziej na koncepcjach domenowych, a mniej na koncepcjach technicznych.

Jedną z funkcji Contexture jest Bounded Context Canvas. Podobnie jak w przypadku Structurizr, obecna iteracja nadal wymaga ręcznych czynności, ale nietrudno wyobrazić sobie przyszłe iteracje narzędzia, które niemal w pełni zautomatyzują proces i wydobywanie wiedzy domenowej z systemu.

Byłem również pod wrażeniem specyfikacji OpenApi (dawniej Swagger). Możliwość przeglądania publicznego interfejsu usługi jest doskonałym przykładem skrócenia krzywej uczenia się i uwidocznienia złożoności.


Przyszłość....

Przyszłość rozwoju oprogramowania będzie obejmować samodokumentujące się architektury, łatwiejsze do nauki, łatwiejsze do rozwijania, a może nawet częściowo projektujące się same.  Będą one dokumentować swój rozwój z czasem, co pozwoli nam uzyskać długofalowe informacje zwrotne na temat naszych wyborów projektowych i lepiej zrozumieć przyczyny podjętych decyzji. Być może nie napotkamy się już na sytuację, w której “wszyscy, którzy pracowali nad tą częścią systemu, odeszli”.

Nie jestem w stanie przewidzieć skali czasowej tych zmian, ale narzędzia takie jak Structurizr i Contexture oraz wyjątkowa praca Cyrille’a Martraire’a napawają optymizmem.

Daj znać, co o tym myślisz. Zostaw komentarz lub uderzaj bezpośrednio do mnie.


Oryginał tekstu w języku angielskim przeczytasz tutaj.

<p>Loading...</p>