Dokumentacja,
która sama się pisze
@technites_pl
Trzy rodzaje dokumentacji
@technites_pl
Podobno wszystko tu miało być
Trzy rodzaje dokumentacji
To na pewno
gdzieś tu jest
@technites_pl
Trzy rodzaje dokumentacji
@technites_pl
To nasz najnowszy model
... jedynie 30 lat temu
Po co nam w ogóle dokumentacja ?
@technites_pl
Nie wnikaj, taki mamy wymóg
Po co nam w ogóle dokumentacja ?
@technites_pl
Musimy to pokazać na spotkaniu
Po co nam w ogóle dokumentacja ?
@technites_pl
A może zespół jej potrzebuje ?
Tylko czego on w zasadzie potrzebuje ?
Codzienne pytania
@technites_pl
- Architekt:
Jaka jest relacja między jednostkami wdrożeniowymi
a granicami modelu domenowego ? - Lider zespołu:
Z jakimi innymi modułami integrują się moduły, którymi opiekuje się mój zespół ? - Deweloper:
Jakie elementy modelu domenowego realizują ten
use case i jakie struktury w kodzie je implementują ?
Codzienne pytania
@technites_pl
- Product Owner:
Jakie zespoły są zaangażowane w ten proces ? - Tester:
Jakie reguły są pilnowane przez elementy,
które realizują ten use case ? - Ekspert domenowy:
Na jakie procesy będzie wpływała zmiana tego elementu modelu ? - etc., etc., etc.
Co jest pod spodem ?
@technites_pl
Co jest pod spodem ?
@technites_pl
Na sprint review niestety nie widać wszystkiego
Szerszy kontekst
Dziwne, każda historyjka osobno wyglądała dobrze ...
@technites_pl
Wspólna reprezentacja
@technites_pl
Gdyby można było zobaczyć efekt,
zanim będzie
za późno ...
Spojrzenie z innej perspektywy
@technites_pl
Kod nie zawsze jest
optymalną reprezentacją
@technites_pl
zrozumienie biznesu i
aktualnego rozwiązania
Software development is a learning process,
working code is a side effect.
- Alberto Brandolini
szybsze i bezpieczniejsze
dostarczanie na produkcję
@technites_pl
Dokumentacja powinna zapewniać
efektywny wgląd w projektowany system
we wszystkich jego aspektach
dla osób o różnych kompetencjach
Skoro to takie ważne,
to dlaczego dobrej dokumentacji (prawie)zawsze brakuje ?
@technites_pl
- brak świadomości ?
- lenistwo ?
- natłok pracy ?
A może przyczyna jest gdzieś głębiej ?
Jak to wygląda
w budownictwie ?
@technites_pl
Jak często wprowadzane są zmiany?
A jak to wygląda
w IT ?
@technites_pl
Jak często wprowadzane są zmiany?
public class Order
{
public void Place()
{
...
}
...
}
public interface DiscountPolicy
{
...
}@technites_pl
Dlaczego tak jest ?
Manufacturing is a popular metaphor for software development [...]
This metaphor has messed up a lot of projects for one simple reason
- software development is all design.
-Eric Evans
@technites_pl
Pełna dokumentacja nie może
powstać przed kodowaniem
bo projektowania nie da się oddzielić
od implementacji
Aktualna dokumentacja nie może
powstać po implementacji,
bo zmiany są zbyt częste
Dokumentację powinno
dać się wygenerować z kodu
@technites_pl
most knowledge is already there
- Cyrille Martraire
living
=
samoaktualizująca
Dokumentację powinno
dać się wygenerować z kodu
@technites_pl
- struktura typów
- struktura katalogów
- testy automatyczne
- API
- Infrastructure as Code
- tracing
- git
- ...
A może kod wygenerować
z dokumentacji ?
@technites_pl
Ciężko jest
automatycznie uzupełnić brakujące informacje
Prawo automatycznych transformacji
@technites_pl
\forall f: f(code) = doc
f(.....) =
@technites_pl
@technites_pl
Tylko kod ma gwarancję aktualności, więc wokół niego trzeba zbudować narzędzia zapewniające wgląd w projektowany system
Żeby było to możliwe
kod musi mieć strukturę opartą o
dobrze zdefiniowane abstrakcje
Wieloznaczność terminów
@technites_pl
Problem jest w tym,
że nasze abstrakcje nie są jeszcze
dobrze usystematyzowane:
- serwis
- komponent
- moduł
- kontener
- test jednostkowy
- ...
Odrzucenie abstrakcji nie jest
rozwiązaniem tego problemu
@technites_pl
Kod z abstrakcjami
nie gwarantuje czytelności
Kod bez abstrakcji
gwarantuje brak czytelności
@technites_pl
To co potrzebne
do zrozumienia
To co potrzebne
do kompilacji
Czy w kodzie jest wszystko czego potrzebujemy ?
Metadane w kodzie
@technites_pl
[DddAggregate]
[CoreConcept]
public class Order
{
...
}
[DddValueObject]
public class Offer
{
...
}# ADR 007
## Kontekst
...
## Decyzja
...
## Alternatywa
...[CqrsCommand]
[BusinessProcess("WholesaleOrdering")]
public class PlaceOrder
{
...
}[GofAbstractFactory]
[Exemplary]
public class PricingPolicies
{
...
}[assembly:DeployableUnit("Search", "ADR 007")][assembly:Tier(ThreeTiers.Application)][PublicContract]
public class PassengerType
{
...
}Metadane w kodzie
@technites_pl
@technites_pl
Brakujące informacje lepiej
dodać do kodu
w postaci metadanych,
niż pozwolić im dezaktualizować się
z dala od niego
Skala wyzwania
@technites_pl
- wiele rodzajów informacji
- domena
- projekt techniczny
- ludzie
- wiele osób o różnych kompetencjach
- deweloperzy
- architekci
- analitycy
- testerzy
- eksperci domenowi
Powrót do korzeni
@technites_pl
A software architecture is a complex entity that cannot be described in a simple
one-dimensional fashion
- pierwsze artykuły - 1974
- 4+1 - 1995
- Siemens Four View model - 2000
- CAFCR - 2005
Jak to jest
w innych branżach ?
@technites_pl
wikipedia.org
chiefarchitect.com
rodzaj mapy = perspektywa
@technites_pl
np:
- granice modelu domenowego
- jednostki wdrożeniowe
- podział na zespoły
@technites_pl
abstrakcje + metadane w kodzie
automatyczne parsowanie
surowe dane do dokumentacji
wgląd z różnych perspektyw
narzędzia do wizualizacji
@technites_pl
Na system można patrzeć
z wielu perspektyw
Do jego zrozumienia
potrzebujemy ich wszystkich
Remanent narzędzi
@technites_pl
@technites_pl
|
|
|
||
|---|---|---|---|
| Domain | |||
| Technology | |||
| People | |||
| Living |
@technites_pl
Logs
Metrics
Traces
Observability
Połączone narzędzia potrafią więcej
@technites_pl
|
|
P3 Model |
|---|---|
| Domain | |
| Technology | |
| People | |
| Living |
3 perspectives
@technites_pl
Potrzebujemy dokumentacji
żeby efektywnie rozwijać systemy
a to co mamy zwykle nie jest zbyt użyteczne
Nie chcemy jej robić ręcznie
bo wtedy jest wiecznie nieaktualna
Musimy generować ją z kodu
Kod musi mieć czytelną strukturę
i metadane
@technites_pl
Mamy do tego gotowe narzędzia
ale żadne z nich nie obejmuje wszystkich aspektów
Potrzebujemy czegoś więcej
P3 Model
Domain - Technology - People
Zapraszamy Was do tworzenia P3
Wspólnie rozwiążmy problem nieaktualnej
i bezużytecznej dokumentacji
@technites_pl
P3 Model
GitHub P3-model
Przykład użycia
GitHub DDD-starter-dotnet
Testowanie architektury
(bonus)
@technites_pl
Mając informacje o zamierzonych wzorcach,
można automatycznie przetestować,
czy kod jest z nimi zgodny
Może w tym pomóc np:
noClasses().that().resideInAPackage("..Core..")
.should().dependOnClassesThat().resideInAPackage("..UseCases..")Code Review
(bonus)
@technites_pl
Mając informacje o modelu domenowym, sposobie wdrażania, scenariuszach biznesowych, etc.
można automatycznie wykrywać:
- nowe pojęcia domenowe
- reguły, które zostały usunięte
- nowe zależności między mikroserwisami
- procesy, które się zmieniły
- ...
@technites_pl
Mechanika nawigacji
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
@technites_pl
Dokumentacja, która sama się pisze
By Marcin Markowski
