Nie, pokazuj operacje potrzebne do celu diagramu#

Diagram klas nie musi zawierać wszystkich metod z kodu ani wszystkich operacji z repozytorium modelu. Pokazuj te operacje, które pomagają odpowiedzieć na konkretne pytanie: jakie odpowiedzialności ma klasa, jakie kontrakty udostępnia, jak współpracuje z innymi elementami albo jak wygląda publiczny interfejs. Pełna lista jest uzasadniona wtedy, gdy diagram służy specyfikacji lub weryfikacji kompletnego API.

Każdy diagram ma określonego odbiorcę i poziom abstrakcji. Analityczny diagram dziedziny może pominąć metody techniczne; diagram projektu może pokazać operacje publiczne; wygenerowany widok API może zawierać pełne sygnatury. Wybieraj poziom szczegółowości świadomie, a nie przez eksport wszystkiego z narzędzia.

Co warto pokazać#

Dodaj operację, jeśli wyraża ważną odpowiedzialność klasy, publiczną usługę, kontrakt interfejsu, istotne zachowanie podtypu albo zależność używaną w scenariuszu. Pokazuj typy parametrów i wyników, gdy są potrzebne do jednoznaczności. Widoczność (+, -, #, ~) uwzględnij, jeśli diagram dotyczy enkapsulacji albo publicznego API.

Warto pokazać operacje abstrakcyjne, gdy wyznaczają wymagany kontrakt podtypów. Można pominąć operacje dziedziczone, jeśli ich ponowne wyświetlanie tworzy szum. W diagramie klas pojęciowych często ważniejsze są nazwy konceptów, atrybuty i relacje niż szczegóły implementacji.

Co zwykle pominąć#

Operacje akcesorów (getX, setX), wygenerowane konstruktory, metody pomocnicze, szczegóły frameworka oraz trywialne delegacje zwykle nie pomagają w komunikacji architektury. Pominąć można także operacje niezwiązane z pytaniem diagramu, o ile brak nie zmienia jego interpretacji.

Nie pomijaj szczegółu tylko dlatego, że jest techniczny. Jeśli typ argumentu, widoczność lub operacja wyjątkowa wpływa na kontrakt bezpieczeństwa, integrację, granicę modułu albo zachowanie klienta, pokaż ją albo odwołaj się do dokładniejszej specyfikacji.

Operacja a metoda#

W UML operacja opisuje cechę zachowania klasyfikatora, natomiast metoda jest implementacją operacji. Diagram klas zwykle pokazuje operacje modelu; może nie ujawniać, jak są zrealizowane. Kod może mieć kilka metod realizujących tę samą operację albo implementować zachowanie inaczej niż sugeruje prosty widok.

W praktycznej rozmowie terminy bywają używane zamiennie, ale w specyfikacji rozróżnienie jest przydatne. Jeśli diagram ma opisywać publiczne API konkretnego języka, wyraźnie zaznacz platformę i uwzględnij jej reguły przeciążania, generyków, asynchroniczności czy wyjątków.

Zasady ograniczania złożoności#

  • Zacznij od pytania, na które diagram ma odpowiedzieć.
  • Pokaż nazwy operacji i typy, które wpływają na odpowiedzialność lub zgodność kontraktu.
  • Pomiń szczegóły, które można znaleźć w kodzie lub osobnej dokumentacji, jeśli nie są tu potrzebne.
  • Rozdziel diagram pojęciowy, projektowy i referencyjny zamiast łączyć je w jedną planszę.
  • Użyj notatki lub osobnej tabeli API, jeśli zestaw operacji jest obszerny.
  • Ustal, czytelnik ma rozumieć dziedziczenie, widoczność czy wywołania — każdy cel wymaga innego zestawu elementów.

Ryzyko niespójności z kodem#

Ręcznie utrzymywany diagram z każdą metodą szybko się dezaktualizuje. Jeśli pełna sygnatura jest niezbędna, rozważ generowanie diagramu z modelu lub kodu oraz kontroluj różnice w procesie zmian. Generowany obraz nadal wymaga oceny, czy zachowuje czytelność i pokazuje znaczące relacje.

Diagram abstrakcyjny może celowo różnić się od kodu, bo opisuje architekturę lub domenę. W takim przypadku jego uproszczenie nie jest błędem, o ile zakres i źródło prawdy są zrozumiałe. Nie przedstawiaj diagramu jako aktualnej listy metod, jeśli nim nie jest.

Typowe błędy#

  • Eksport wszystkich metod bez celu. Pełny widok może ukryć najważniejsze odpowiedzialności.
  • Traktowanie braku metody na diagramie jako braku w kodzie. Zależy to od zakresu widoku.
  • Operacja utożsamiona z implementacją. Model może opisywać kontrakt bez szczegółów metody.
  • Pomijanie publicznego kontraktu integracyjnego. Istotne operacje powinny być widoczne w odpowiednim widoku.
  • Mieszanie poziomów abstrakcji. Metody domenowe i pomocnicze mogą nie pasować do jednego diagramu.
  • Ręczne przepisywanie API bez aktualizacji. Zdecyduj, czy diagram jest źródłem prawdy, generowanym artefaktem czy przeglądowym szkicem.
  • Usunięcie wszystkich operacji w imię prostoty. Jeśli zachowanie jest pytaniem diagramu, pokaż reprezentatywne operacje.

Podsumowanie#

Pokazuj operacje, które wspierają cel i odbiorców diagramu, a nie automatycznie całą zawartość klasy. Pełne sygnatury są przydatne w specyfikacji API, a selektywny widok lepiej komunikuje architekturę i odpowiedzialności. Ustal zakres oraz sposób utrzymywania diagramu, by brak elementu nie był mylony z brakiem w systemie.