Podcast o Dokumentacja oprogramowania i jej zasady

Přepis

Tomáš: ...czyli najlepszy programista na świecie napisze genialny kod, ale jeśli nie doda do niego ani linijki wyjaśnienia, to tak naprawdę jest to prawie bezużyteczne?

Karolína: Dokładnie tak! To jak wynaleźć najlepszy silnik na świecie, a potem wyrzucić instrukcję obsługi. Nikt go nie naprawi, nikt go nie ulepszy i nikt nie wie, jak go używać!

Tomáš: To świetne porównanie! Witajcie w Studyfi Podcast, gdzie dziś zagłębimy się w świat inżynierii oprogramowania.

Karolína: No to przejdźmy od razu do rzeczy. Sporo ludzi uważa, że pisanie komentarzy w kodzie to strata czasu. „Przecież wiem, co napisałem” – mówią sobie.

Tomáš: Tak, znam to. „Mój kod przecież sam się tłumaczy.” Jasne…

Karolína: Dokładnie. Tyle że to działa tylko do momentu, aż odejdziesz od projektu na tydzień. Albo wystarczy urlop. Potem wracasz, patrzysz na swój własny kod i pytasz: co autor miał na myśli?

Tomáš: A przecież ten autor to ty sam! To zdarzyło mi się więcej razy, niż bym chciał przyznać.

Karolína: To zdarza się każdemu. A to tylko jeden powód. Dzisiejsze oprogramowanie to praca zespołowa. Komentarze to wiadomości dla twoich kolegów, żeby mogli kontynuować twoją myśl. Bez nich jest to prawie niemożliwe.

Tomáš: A co jeśli chcę użyć mojego kodu jako biblioteki dla innych? Czyli dać im narzędzie, ale nie pokazywać, jak dokładnie działa w środku.

Karolína: Świetna uwaga! W takim przypadku wysokiej jakości dokumentacja jest absolutnie kluczowa. Bez niej twoja wspaniała biblioteka byłaby praktycznie bezużyteczna.

Tomáš: No dobrze, więc musimy dokumentować. Czy to znaczy, że do każdego projektu muszę napisać setki stron tekstu? Brzmi jak koszmar.

Karolína: Wcale nie! I to jest w tym piękne. Poziom dokumentacji różni się w zależności od projektu. To nie jest żaden dogmat. Chodzi o efektywność.

Tomáš: Co masz na myśli?

Karolína: Wyobraź sobie, że pracujesz w małym zespole, wszyscy siedzicie w jednym pokoju i rozwijacie prostą aplikację. Domena jest znana. W takim przypadku jako dokumentacja architektury może wam wystarczyć zdjęcie szkicu z tablicy.

Tomáš: Naprawdę? Tylko zdjęcie z telefonu?

Karolína: Dokładnie tak. Czemu nie, jeśli to ma sens dla wszystkich i oszczędza czas? Ale teraz wyobraź sobie odwrotność. Duży, rozproszony zespół, nowa, skomplikowana technologia, nieznany obszar... Tam już będziesz potrzebować znacznie więcej.

Tomáš: Na przykład słownik pojęć, szczegółowe modele, jak komponenty komunikują się ze sobą i tak dalej?

Karolína: Dokładnie. Celem nie jest stworzenie jak największej ilości dokumentacji, ale właściwej dokumentacji dla danego projektu.

Tomáš: Dobrze, powiedzmy, że mamy bardziej złożony projekt. Co konkretnie powinniśmy uwzględnić w dokumentacji architektury?

Karolína: Powinniśmy uwzględnić kilka podstawowych widoków systemu. Po pierwsze, widok statyczny – z jakich części składa się aplikacja. Możesz to sobie wyobrazić jako plan budynku. Tutaj są klasy, tutaj są pakiety.

Tomáš: Rozumiem. A dalej?

Karolína: Po drugie, zachowanie dynamiczne. Czyli jak te poszczególne części komunikują się ze sobą. To tak jakby obserwować, jak ludzie w tym budynku przechodzą z pokoju do pokoju. Do tego świetnie nadają się na przykład diagramy sekwencji z UML.

Tomáš: A co z perspektywą użytkownika? Jego przecież nie interesuje, jakie mamy klasy.

Karolína: Dokładnie! To jest trzeci kluczowy widok. Do tego służą tak zwane „use case”, czyli przypadki użycia. One opisują, co system robi z perspektywy użytkownika, jakie funkcje mu oferuje. To jest widok funkcjonalny.

Tomáš: Czyli mamy różne modele, różne widoki... Czy nie może się zdarzyć, że będziemy mieli tego za dużo? Że w tej dokumentacji w końcu się pogubimy?

Karolína: Może, i to jest ogromne ryzyko! Im więcej masz dokumentacji i im w więcej miejscach powtarzasz te same informacje, tym więcej pracy masz z jej aktualizacją.

Tomáš: A tym większa szansa, że gdzieś będzie błąd lub niespójność. W jednym dokumencie będzie wersja A, w drugim wersja B.

Karolína: Dokładnie tak! Dlatego ja osobiście preferuję minimalistyczne, efektywne podejście. Istnieją też bardzo naukowe metody, na przykład z Software Engineering Institute, które patrzą na dokumentację prawie jak na osobną dyscyplinę naukową.

Tomáš: Czyli mniej znaczy czasem więcej, jeśli nie chcesz skończyć z dokumentacją, która jest dłuższa i bardziej skomplikowana niż sam kod?

Karolína: Dokładnie to ująłeś. Celem jest zrozumiałość i efektywność, a nie stosy papieru.

Tomáš: To wszystko brzmi jak mnóstwo pracy. Czy istnieją jakieś narzędzia, które ułatwiłyby nam tę, przyznajmy, czasem nieprzyjemną pracę?

Karolína: Oczywiście. Nie musimy wszystkiego pisać ręcznie. Istnieją świetne narzędzia, które potrafią generować dokumentację bezpośrednio z kodu źródłowego. Na przykład Java ma narzędzie o nazwie JavaDoc.

Tomáš: Czyli jeśli piszę komentarze w odpowiedni sposób bezpośrednio w kodzie, program sam mi z tego potem stworzy ładną dokumentację?

Karolína: Dokładnie tak! To jeden z najefektywniejszych sposobów. Kolejną technologią, która w tym bardzo pomaga, jest XML. Ale o tym opowiemy więcej na przykład następnym razem.

Tomáš: Dobrze, więc omówiliśmy projekt i specyfikację... ale teraz przychodzi mi do głowy jedna rzecz, którą programiści, których znam, absolutnie uwielbiają. Dokumentacja.

Karolína: Tak, strzał w dziesiątkę! Poprosić programistę o napisanie dokumentacji to chyba jak poprosić kota, żeby wziął kąpiel. Po prostu nie chcą tego robić.

Tomáš: To świetne porównanie! Ale dlaczego to jest właściwie takie ważne, skoro wszyscy tego tak nienawidzą?

Karolína: Bo oprogramowanie nigdy nie żyje w próżni. Nie robimy tego tylko dla siebie. Wyobraź sobie to tak... zespół utrzymania potrzebuje wiedzieć, jak system jest zbudowany, żeby móc go naprawić. Testerzy z kolei muszą wiedzieć, co dokładnie system ma robić, żeby mogli sprawdzić, czy robi to prawidłowo.

Tomáš: I oczywiście klienci...

Karolína: Dokładnie! Klienci potrzebują instrukcji obsługi, żeby wiedzieli, w co mają klikać. Każda rola potrzebuje innego widoku, innego typu informacji. Dokumentacja to ten most między nimi.

Tomáš: Dobrze, to ma sens. Czyli musimy mieć stosy papierów i dziesiątki dokumentów dla każdego projektu?

Karolína: Wcale nie! I to jest kluczowe. W świecie agile obowiązuje zasada, że forma nie jest tak ważna jak treść. Nie chodzi o to, żeby mieć metrowe stosy papieru, ale o to, czy w ogóle mamy tę informację i czy ją udostępniamy.

Tomáš: Czyli mniej znaczy czasem więcej?

Karolína: Dokładnie. W przypadku małego zespołu, który siedzi w jednym pokoju i wszyscy wiedzą, nad czym pracują, wystarczy na przykład kilka diagramów na tablicy i dobrze skomentowany kod. Natomiast w przypadku ogromnego międzynarodowego projektu z dziesiątkami zespołów... tam już potrzebujemy bardziej formalnej i szczegółowej dokumentacji.

Tomáš: Czyli zależy od kontekstu. Nie ma jednego uniwersalnego rozwiązania dla wszystkich.

Karolína: Bingo! To jest dokładnie to. Celem jest posiadanie *wystarczającej* dokumentacji, a nie *maksymalnej*. Chcemy efektywności, a nie biurokracji.

Tomáš: Fajnie, to rozumiem. Czy istnieją jakieś narzędzia, które ułatwiłyby nam tę niepopularną pracę?

Karolína: Oczywiście! Programiści są sprytni i leniwi, więc wymyślili sposoby, jak to zautomatyzować. Świetnym przykładem jest JavaDoc. To narzędzie dla języka Java.

Tomáš: Jak to działa?

Karolína: Prosto. Piszesz komentarze bezpośrednio w kodzie według określonych zasad. Potem uruchamiasz narzędzie JavaDoc i ono automatycznie generuje ci z tych komentarzy ładną, przejrzystą dokumentację techniczną w formacie HTML. Nie musisz nic pisać dwa razy.

Tomáš: To brzmi świetnie! A co z jakimiś ogólniejszymi standardami? Coś jak... przepis na dobrą dokumentację?

Karolína: Istnieje. Na przykład standard IEEE 1063. On w zasadzie mówi, co powinna minimalnie zawierać wysokiej jakości dokumentacja użytkownika. Jaką ma mieć strukturę, format, że musi być kompletna, dokładna... To taka wskazówka, żeby o niczym ważnym nie zapomnieć.

Tomáš: Czyli nie musimy na nowo wymyślać koła.

Karolína: Dokładnie. Możemy oprzeć się na sprawdzonych praktykach.

Tomáš: Wspomniałaś, że z JavaDocem nie musimy pisać rzeczy dwa razy. To chyba główna myśl, prawda?

Karolína: Zdecydowanie! Zasada ponownego użycia jest tutaj absolutnie kluczowa. Nie chcemy tworzyć dokumentów, które potem tylko leżą odłogiem. Staramy się wykorzystać to, co już mamy.

Tomáš: Jak na przykład co konkretnie?

Karolína: Pamiętasz, jak rozmawialiśmy o scenariuszach use case, gdzie opisujemy, jak użytkownik wchodzi w interakcję z systemem? Na przykład wypłata pieniędzy z bankomatu.

Tomáš: Jasne, te kroki, które się dzieją.

Karolína: Więc dokładnie te tekstowe scenariusze możesz wziąć, lekko je zmodyfikować, dodać kilka obrazków i masz gotowy rozdział do instrukcji obsługi. Zaoszczędziłeś mnóstwo pracy i zapewniłeś, że podręcznik odpowiada pierwotnym wymaganiom.

Tomáš: Wow, to sprytne. Czyli dokumentacja tak naprawdę nie musi być takim koszmarem. Chodzi raczej o sprytne podejście i wykorzystanie tego, co już istnieje.

Karolína: Dokładnie tak. To kolejny element układanki inżynierii oprogramowania. A skoro już jesteśmy przy układaniu... kolejnym kluczowym elementem jest sama implementacja i testowanie, którym przyjrzymy się następnym razem.

Tomáš: Czyli omówiliśmy, jak HTML nadaje strukturę stronie internetowej dla ludzi. Ale co jeśli potrzebujemy, żeby komputery też rozumiały znaczenie tych danych?

Karolína: Dokładnie tak, Tomášu! I właśnie tutaj na scenę wkracza XML, czyli Extensible Markup Language.

Tomáš: Rozszerzalny język znaczników... To brzmi ważnie.

Karolína: I tak jest! Wyobraź sobie to tak... w XML możesz tworzyć własne, zupełnie specyficzne znaczniki, tak zwane tagi. Więc zamiast ogólnego tagu masz na przykład <autor>, <nazwa> albo <wersja>. Od razu wiesz, o co chodzi.

Tomáš: Aha! Czyli te dane same niosą swój opis. To musi być absolutnie świetne do wyszukiwania i przetwarzania maszynowego.

Karolína: Dokładnie! Ale z tą swobodą wiąże się też duża odpowiedzialność. XML ma bowiem znacznie bardziej rygorystyczne zasady niż HTML.

Tomáš: Jakie zasady na przykład? Żadnych zapomnianych tagów zamykających?

Karolína: W żadnym wypadku! Wszystkie tagi muszą być sparowane. Co więcej, XML rozróżnia wielkie i małe litery, więc <Tag> i <tag> to dwie zupełnie inne rzeczy.

Tomáš: Rozumiem, jest to case-sensitive. Co dalej?

Karolína: Każdy dokument musi mieć dokładnie jeden element główny, który obejmuje wszystko inne. A wartości atrybutów muszą być zawsze w cudzysłowach. Żadnych wyjątków.

Tomáš: To wygląda prawie... matematycznie precyzyjnie. Ale skąd system wie, jaka struktura jest poprawna?

Karolína: Świetne pytanie! Do tego używa się DTD lub tak zwanego Schematu XML, które definiują dozwoloną strukturę. Ale do tego przejdziemy zaraz.

Tomáš: Dobrze, omówiliśmy naprawdę sporo. Ale mamy przed sobą ostatni duży temat... Javę. I przede wszystkim, jak nie zgubić się we własnym kodzie.

Karolína: Dokładnie tak! I to prowadzi nas do czegoś, co nazywa się Javadoc. To niesamowicie przydatne narzędzie od Sun Microsystems.

Tomáš: Javadoc... brzmi to prawie jak jakieś prawo. Co to dokładnie robi?

Karolína: Wyobraź sobie to tak. To narzędzie, które automatycznie generuje stronę internetową z dokumentacją bezpośrednio z komentarzy w twoim kodzie źródłowym. Dla dokumentacji API to absolutne wybawienie.

Tomáš: Czyli napiszę komentarz, a on stanie się częścią profesjonalnie wyglądającej strony internetowej? To świetnie.

Karolína: W zasadzie tak! Ale jest pewien haczyk. To narzędzie jest sprytne, ale nie umie czytać w myślach. Jeśli nazwiesz swoją klasę na przykład 'Pr' i nie napiszesz zrozumiałych komentarzy, to wynikowa dokumentacja będzie do niczego.

Tomáš: Jasne. Śmieci wchodzą, śmieci wychodzą. Czyli automatyzuje formatowanie, ale jakość treści nadal zależy od ciebie.

Karolína: Dokładnie tak. Pomoże ci to zbudować dom, ale cegły musisz dostarczyć sam. Dobre komentarze i sensowne nazwy to podstawa.

Tomáš: To idealna kropka nad i. Dobre nawyki są kluczowe. Karolino, to na dziś wszystko. Przeszliśmy przez wszystko od schematów XML aż po Javę. Wielkie dzięki, że nam to wszystko wyjaśniłaś.

Karolína: Cała przyjemność po mojej stronie! Dzięki za zaproszenie.

Tomáš: I dzięki wszystkim za wysłuchanie Studyfi Podcastu. Usłyszymy się następnym razem!