Dołączyłem do projektu średniej wielkości, który trwa już od kilku lat. Jednym z problemów jest to, że dokument opisujący architekturę nigdy nie został napisany. Teraz przydzielono mi zadanie napisania opisu architektury.

Podczas pracy nad tym projektem zebrałem wszystkie informacje potrzebne do napisania dokumentu. Ponieważ dodałem także niektóre funkcje, zidentyfikowałem niektóre fragmenty kodu, które wyraźnie łamią architekturę, jak to opisano.

Na przykład GUI miał być cienką warstwą bez logiki biznesowej. Tak mi powiedziano. Implementacja zawiera wiele logiki.

Mój szef zlecił mi zadanie napisania dokumentu opisującego architekturę systemu. Docelowi odbiorcy to obecni i przyszli programiści pracujący nad projektem. Muszę opisać, co powinno być, ale muszę też jakoś opisać odchylenia.

Gdzie więc powinienem opisać te problemy? Oprogramowanie do śledzenia błędów? Czy powinienem opisać odchylenia implementacji od architektury w dokumencie opisującym architekturę systemu?

Jeśli dokumentujesz projekt lub architekturę systemu, który już został zbudowany, dokument powinien opisywać go jako zbudowany, a nie jako zaprojektowany lub zgodny z przeznaczeniem. Jeśli w architekturze występują osobliwości lub rozbieżności, dokument ten powinien wskazać te problemy i wyjaśnić je w jak największym stopniu czytelnikowi.

Jeśli możesz uzyskać informacje od osób, które pracowały nad systemem od samego początku (lub przynajmniej dłużej niż masz), przydatne byłoby przechwycenie większej ilości informacji o tym, co faktycznie było zamierzone i dlaczego architektura i projekt odbiegają od tego zamiar.

Ostatecznie dokument projektowy powinien służyć jako przewodnik po kodzie. Jeśli dokument nie pomaga nowemu programistowi zrozumieć obecnego stanu bazy kodu i jego struktury, oznacza to, że dokument nie jest użyteczny.

Dokument ten powinien być żywym dokumentem, który służy do kierowania przyszłym planowaniem i projektowaniem zmian w systemie, a następnie odpowiednio aktualizowany w ramach procesu rozwoju. Ponieważ projekt zmienia się i ewoluuje w czasie, dokument powinien również pomóc programistom zrozumieć, dlaczego rzeczy są takie, jakie są obecnie.

Jeśli szukasz porady na temat uchwycenia architektury, podoba mi się podejście zalecane w IEEE Standard 1016-2009 IEEE Standard for Information Technology - Projektowanie systemów - Opis projektowania oprogramowania . Zapewnia rozsądną strukturę opisu projektu, która może być wykorzystana do przechwytywania informacji projektowych zarówno na poziomie architektonicznym, jak i szczegółowym.

Uważam również, że te odchylenia są formą długu technicznego. Rozwiązanie problemu może być dużym przedsięwzięciem, a może nawet małym projektem, zaleciłbym uczynienie istnienia długu technicznego bardziej widocznym. Jeśli to oznacza, że ​​korzystasz z narzędzia do śledzenia defektów, możesz umieścić tam jeden lub więcej problemów. Jeśli masz inne narzędzie, którego używasz do śledzenia sugestii i ulepszeń oprogramowania, może to być inne miejsce na umieszczenie go.

Podczas formalizowania architektury systemu ważne jest, aby zrozumieć nie tylko wartość stojącą za tym, co architektura przyniesie na stół, ale także zrozumieć i docenić, jaka powinna być.

Podstawowym celem oprogramowania lub architektury technicznej jest identyfikacja niefunkcjonalnych wymagań, które są realizowane przez atrybuty jakości, które będą sterować architekturą systemu .

Wymagania niefunkcjonalne:

Wymaganie niefunkcjonalne to wymaganie określające kryteria, które można wykorzystać do oceny działania systemu, a nie określone zachowania. Kontrastują z wymaganiami funkcjonalnymi, które definiują określone zachowanie lub funkcje. Plan wdrożenia wymagań funkcjonalnych jest szczegółowo opisany w projekcie systemu. Plan wdrożenia wymagań niefunkcjonalnych jest szczegółowo opisany w architekturze systemu.

Zasadniczo wymagania funkcjonalne określają, co powinien robić system, a wymagania niefunkcjonalne określają, jak powinien wyglądać system. ... Wymagania niefunkcjonalne są często nazywane „atrybutami jakości” systemu. Inne terminy dotyczące wymagań niefunkcjonalnych to „cechy”, „cele jakości”, „wymagania dotyczące jakości usługi”, „ograniczenia” i „wymagania niedziałające”

Oczywiście określenie wymagań architektonicznych ma sens w przypadku projektu typu greenfield, jednak podczas pracy z istniejącym oprogramowaniem najlepiej jest zachować jak największą dyscyplinę. Nie będziesz chciał, aby istniejący system wpływał na twoją architekturę oprogramowania.

Architektura oprogramowania, aby być autorytatywnym, naprawdę musi mieć 3 rzeczy.

Deklaracyjny

Jest to część dokumentacji, w której deklarujesz NIE TO, CO JEST, ale jak POWINIEN BYĆ. Robimy to za pomocą różnych widoków architektonicznych systemu. Definiujemy komponenty, które powinny być, w jaki sposób wchodzą w interakcje, a następnie opcjonalnie przechodzimy do każdego komponentu, aby uzyskać bardziej szczegółowe widoki, które deklarują sposób zaprojektowania systemu.

To ważne rozróżnienie. Projektowanie systemu powinno być ograniczone przez architekturę systemu, w rzeczywistości są to oddzielne, ale powiązane rzeczy.

Racjonalne uzasadnienie

Uzasadnienie architektury oprogramowania zapewnia uzasadnienie i autorytet podjętych decyzji dotyczących architektury. Być może podjęto decyzję o wykorzystaniu nasłuchiwania zdarzeń Pub / Sub nad MQ do uruchomienia zadania wsadowego, a ty go wykreślisz?

Dlaczego podjęto tę decyzję? Wyjaśnimy dlaczego w sekcji uzasadnienia i powrócimy do naszego wyjaśnienia do wymagań niefunkcjonalnych, celów atrybutów jakości lub wymagań istotnych architektonicznie. (Np. Zadania muszą być asynchroniczne i powtarzalne, Utrzymywalność jako atrybut jakości steruje tym, że w przypadku niepowodzenia zadania wsadowego zadania mogą zostać ponownie zainicjowane za pomocą komunikatu MQ, System musi mieć zerową utratę wiadomości z komunikacją asynchroniczną itp. ..)

Ryzyko

Teraz, gdy zadeklarowałeś, jak powinna wyglądać architektura i udowodniłeś to za pomocą uzasadnienia, możesz teraz zidentyfikować ryzyko w obecnym stanie systemu, w którym nie ma to miejsca.

(Np. Walidacja po stronie serwera jest powielana po stronie klienta Kod JavaScript. Jest to naruszenie zasady DRY, co jest sprzeczne z atrybutem jakości utrzymania. Nie ma żadnych niefunkcjonalnych wymagań dotyczących wydajności w tym obszarze, więc nie ma uzasadnienia dla obecnego zachowania systemu)

Twoje ryzyko może również wykreślić, gdzie obecny stan odbiega obecnie od architektury. Zespołowi programistycznemu można teraz zaradzić tym zagrożeniom poprzez plan projektu lub dodanie tego do zaległości.

Naprawdę musisz zdecydować, czy chcesz dokumentować bieżącą strukturę projektu, pożądaną strukturę projektu, czy obie te rzeczy .

Możesz udokumentować cel, aby poprowadzić przyszły rozwój zgodnie z pożądanymi kierunkami i podnieść odchylenia jako błędy (być może link do tych błędów z odpowiednich części dokumentu). Lub możesz udokumentować rzeczywistość, aby przedstawić wprowadzenie / przegląd kodu. Lub możesz udokumentować obie strony obok siebie, dzięki czemu w jednym miejscu masz przewodnik dotyczący przyszłego rozwoju i dokładny opis bieżącego kodu. Wszystkie są rozsądne, w zależności od tego, do czego dokument ma być, więc nie sądzę, że możemy pożytecznie powiedzieć, który z nich zrobić.

Należy również pamiętać, że pożądana architektura może nie być powszechnie uzgodniona między zaangażowanymi stronami (albo dlatego, że chcą różnych rzeczy, albo dlatego, że niektóre z nich zdały sobie sprawę, że niektóre oryginalne wspólne pragnienia były niemożliwe lub niepraktyczne i dlatego uciekły się do napisania istniejącego kodu co odbiega od celu). Musisz więc również wiedzieć, czy masz uprawnienia do decydowania o tym, co jest pożądane, a jeśli nie, kto to robi. Istniejąca struktura ma przynajmniej tę zaletę, że jest tylko jedna do udokumentowania!

Napisz w dokumencie projektu architektury, co powinno być, a dla każdego konfliktu znajdziesz bilet w module śledzenia błędów opisującym konflikt. Sekcja komentarzy do biletu będzie stanowić platformę dla odpowiednich osób do omawiania tego konkretnego konfliktu.

Pamiętaj, że rozdzielczością każdego z tych biletów może być zmiana implementacji w celu dopasowania do projektu - ale może to być również zmiana projektu w celu dopasowania do implementacji. Najlepiej jest wybrać to pierwsze, ale czasami istnieją ograniczenia techniczne i / lub biznesowe, które sprawiają, że wybranie później jest bardziej wydajne / pragmatyczne /. W takim przypadku dobrym pomysłem może być odwołanie się do zgłoszenia z dokumentu projektowego architektury, aby przyszli czytelnicy, którzy nie rozumieją, dlaczego wybrano ten konkretny wybór, mogą przeczytać dyskusję w zgłoszeniu i zrozumieć uzasadnienie to.

Byłbym skłonny napisać dokument architektoniczny podzielony na 3 główne sekcje.

Pierwszy wprowadzający projekt / architekturę, która była pierwotnie zamierzona. Pozwoli to nowym programistom / czytelnikom na zorientowanie się, co powinien zrobić system i oczywiście powinno być powiązane z wymaganiami / przypadkami użycia itp.

Druga część powinna bardzo dokładnie wyjaśnić, czym właściwie jest architektura . Dzięki temu nowi programiści / czytelnicy mogą zorientować się w bieżącej sytuacji i z czym mają do czynienia, jeśli spojrzą na oprogramowanie (i potencjalnie inną dokumentację). Ta sekcja powinna wyraźnie wskazywać na różnicę między tym, co było zamierzone, a rzeczywistością, ponieważ najprawdopodobniej uwypukli to, co albo jest bardzo złe w oryginalnej architekturze (mam nadzieję, że nie za dużo!), A obszarami, w których skróty / włamania (prawdopodobnie sporo, jeśli było wywierano duży nacisk na zespół programistów) i wymagania nie są spełniane lub oprogramowanie zaczyna wyglądać „źle” zaprojektowane, tj. kruche, niestabilne, nieprzenośne.

Wreszcie myślę, że sekcja szczegółowo opisuje zalecenia dotyczące tego, co musi się teraz stać. Powinny to być wszelkie zmiany w architekturze / projekcie oraz plan zmian w oprogramowaniu, aby Twoja wizja stała się rzeczywistością.

Myślę, że obejmuje to (na wysokim poziomie) to, co należy uchwycić. Sposób, w jaki to robisz pod względem podsekcji wykorzystywanego dokumentu lub oprogramowania do śledzenia błędów, zależy od domeny, w której pracujesz / preferencji osobistych / wielkości zespołu / budżetu / skali czasu itp.