Dokumentowanie aplikacji — komentarze, XML doc, dokumentacja użytkownika

Kod, którego nie rozumie nikt poza autorem (a często i sam autor pół roku później), jest w praktyce bezużyteczny w zespole. Dokumentowanie to nie "papierologia" — to inwestycja w czas, który zaoszczędzisz Ty i inni, gdy trzeba będzie coś poprawić, rozbudować albo po prostu ZROZUMIEĆ, jak coś działa. To wymaganie wprost w INF.04.8.2.

Komentarze w kodzie — kiedy pisać, a kiedy NIE. Dobry komentarz tłumaczy DLACZEGO kod robi coś w określony sposób (ukryte założenie, obejście konkretnego problemu, nieoczywista decyzja projektowa) — NIE tłumaczy CO kod robi, jeśli dobrze nazwane zmienne i metody już to pokazują. Komentarz // dodaj 1 do x nad linijką x++; jest bezużyteczny; komentarz // +1 bo API zwraca indeksy od zera, a UI liczy od jedynki jest wartościowy.

Komentarze dokumentujące (XML doc comments) w C# — specjalna forma komentarza zaczynająca się od ///, którą Visual Studio automatycznie zamienia w podpowiedzi (IntelliSense) widoczne dla innych programistów UŻYWAJĄCYCH danej metody, bez potrzeby otwierania jej kodu źródłowego. Najważniejsze znaczniki: <summary> (krótki opis, co metoda robi), <param name="..."> (opis każdego parametru), <returns> (co metoda zwraca), <exception cref="..."> (jakie wyjątki może rzucić i kiedy).

Dokumentacja kodu vs dokumentacja aplikacji — to dwie różne rzeczy. Dokumentacja KODU (komentarze, XML doc) jest dla PROGRAMISTÓW pracujących nad tym samym projektem. Dokumentacja APLIKACJI ma kilka odrębnych odbiorców i form:

• Instrukcja użytkownika — dla osoby KORZYSTAJĄCEJ z gotowej aplikacji: jak zalogować się, jak dodać produkt, jak wygenerować raport — krok po kroku, bez żargonu technicznego, często ze zrzutami ekranu.
• Dokumentacja wdrożenia — dla administratora/programisty INSTALUJĄCEGO aplikację na serwerze: wymagania systemowe, kroki instalacji, konfiguracja bazy danych, zmienne środowiskowe.
• Dokumentacja z testów — zestawienie przeprowadzonych scenariuszy testowych i ich wyników (patrz lekcja 7) — dowód, że aplikacja została sprawdzona przed wdrożeniem.

README — pierwszy dokument, jaki widzi każdy — plik (zwykle README.md) w głównym folderze projektu, opisujący krótko: co robi projekt, jak go uruchomić lokalnie, jakich technologii używa, jak skontaktować się z autorami. To pierwsze miejsce, do którego trafia każdy nowy programista dołączający do projektu.

Dokumentacja "generowana" kontra pisana ręcznie — narzędzia takie jak DocFX czy Swagger/OpenAPI (używane dla Web API, dział Aplikacje webowe) potrafą automatycznie WYGENEROWAĆ czytelną dokumentację API na podstawie komentarzy XML doc i sygnatur metod w kodzie — dzięki temu dokumentacja NIE "rozjeżdża się" z kodem, bo jest z niego bezpośrednio odczytywana.