Sławomir Czerwiński

Teraz pora omówić najtrudniejszą dla mnie regułę zawartą w manifeście zwinności. Co w niej trudnego? Właściwie wszystko jest oczywiste – towarem, jaki dostarcza się klientom jest program komputerowy, a nie dokumentacja techniczna, na podstawie której można ten program napisać. Zatem działające oprogramowanie ma dużo większą wartość niż nawet najbardziej dokładna dokumentacja.

Reguła jest dla mnie trudna do omówienia nie z powodu jej znaczenia, lecz braku porównania – jeszcze nigdy nie widziałem prawdziwej dokumentacji.

Ale jakoś nigdy na to nie narzekałem.

Natomiast często brakowało mi innych źródeł wiedzy o produkcie… i kodzie.

Czym dokumentacja nie jest

W pracy spotkałem się z dwoma typami dokumentów, nazywanych przez twórców dokumentacją.

Często można pobrać „dokumentację” jakiegoś programu ze strony producenta. Dowiemy się z niej, co program robi i jak z niego korzystać. Ja to nazywam instrukcją.

Kiedyś zdarzyło się, że otrzymałem „dokumentację” programu, który… dopiero mieliśmy pisać (świetnie!). Po godzinie lektury byłem święcie przekonany, że chcę ten program kupić… to się nazywa reklama.

Przykład

Raz próbowaliśmy rozpocząć rozwój projektu od napisania wzorowej dokumentacji. Nie chodziło nam o kilka diagramów (te w jakiejś formie i tak by powstały), ale o eleganckie spisanie wymagań, wyodrębnienie przypadków użycia, opisanie modułów, komponentów, klas, interakcji… po prostu pełna dokumentacja.

Gdy po miesiącu pracy mieliśmy tylko diagramy i kilka krótkich opisów, a do ostatecznego terminu pozostały tylko trzy miesiące – stwierdziliśmy, że jednak warto by coś zaimplementować.

Dokumentacja bez dokumentacji

Co jednak robić, gdy na tworzenie dokumentacji nie ma czasu? Można zastosować starą dobrą metodę ze studiów – usiąść, napisać i zaliczyć sprzedać. Ale prawdziwy projekt to nie programik na zaliczenie – trzeba naprawiać błędy, rozszerzać funkcjonalność, zapewniać wsparcie klientom.

Diagramy są potrzebne. Nie muszą one być dokładnie takie, jak późniejszy kod, ale przydają się – pomagają zrozumieć.

Staram się stosować zasadę, żeby przed rozpoczęciem prac nad każdym nowym modułem, wykonać przynajmniej jeden diagram klas lub model dziedziny, przedstawiający przynajmniej główną ideę i najważniejsze zależności. Przydatne są również diagramy przypadków użycia dla bardziej złożonych wymagań (w szczególności bardziej złożonych niż operacje CRUD).

Bardzo duży nacisk kładę też na odpowiednie komentarze w kodzie programu – zwłaszcza komentarze JavaDoc (lub ich odpowiedniki w innych językach). Przydają się szczególnie na etapie konserwacji produktu, gdy trzeba sobie coś przypomnieć.

Na samym końcu polecam programowanie sterowane testami, dzięki któremu nie tylko oszczędza się czas podczas testowania, ale zapisuje się dokładną wiedzę o spodziewanym działaniu testowanych metod.

Podsumowanie

Ogólnie rzecz biorąc, zasada głosi, że należy przede wszystkim stworzyć dobry, działający produkt, a dokumentację – dokładną na tyle, na ile starczy czasu.

Ale nawet, gdy czasu nie ma w ogóle, warto zastosować jakieś inne formy przechowywania wiedzy o produkcie.