Lekcja 8. Dokumentowanie aplikacji — komentarze, XML doc, dokumentacja użytkownika
latwyPo co się tego uczymy?
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.
Teoria
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.
Schemat
RODZAJE DOKUMENTACJI I ICH ODBIORCY ┌─────────────────────────┬──────────────────────────┐ │ Rodzaj dokumentacji │ Odbiorca │ ├─────────────────────────┼──────────────────────────┤ │ Komentarze w kodzie │ programista czytający kod │ │ XML doc (///) │ programista UŻYWAJĄCY metody│ │ README.md │ nowy programista w zespole │ │ Instrukcja użytkownika │ osoba korzystająca z apki │ │ Dokumentacja wdrożenia │ administrator/DevOps │ │ Dokumentacja z testów │ zespół QA / klient │ └─────────────────────────┴──────────────────────────┘
Przykład z życia
Instrukcja obsługi pralki ma zupełnie inną formę dla użytkownika domowego ("wybierz program, wsyp proszek, naciśnij start") niż schemat elektryczny dla serwisanta naprawiającego usterkę — obie dokumentacje opisują TO SAMO urządzenie, ale są napisane dla zupełnie innych odbiorców i w innym celu. Dokładnie tak samo aplikacja potrzebuje różnych rodzajów dokumentacji dla różnych osób: użytkownika końcowego, administratora wdrażającego system i programisty utrzymującego kod.
Rabaty.cs — przykład komentarzy XML doc (///)
using System;
namespace SklepApp.Logika
{
public class Rabaty
{
/// <summary>
/// Oblicza cenę końcową produktu po zastosowaniu rabatu procentowego.
/// </summary>
/// <param name="cenaBazowa">Cena produktu przed rabatem (musi być dodatnia).</param>
/// <param name="procentRabatu">Wysokość rabatu w procentach (0-100).</param>
/// <returns>Cena końcowa po odjęciu rabatu.</returns>
/// <exception cref="ArgumentException">
/// Rzucany, gdy procentRabatu jest poza zakresem 0-100
/// lub cenaBazowa jest ujemna.
/// </exception>
public decimal ObliczCeneZRabatem(decimal cenaBazowa, double procentRabatu)
{
if (cenaBazowa < )
throw new ArgumentException("Cena bazowa nie może być ujemna.");
if (procentRabatu < || procentRabatu > 100)
throw new ArgumentException("Rabat musi mieścić się w zakresie 0-100%.");
// Zaokrąglamy do pełnych groszy (2 miejsca po przecinku) -
// wymóg zgodności z fakturami VAT, gdzie liczy się grosze, nie ułamki grosza.
decimal wspolczynnik = 1 - (decimal)(procentRabatu / 100.0);
return Math.Round(cenaBazowa * wspolczynnik, 2);
}
}
}Komentarz i wyjaśnienie kodu
Znaczniki <summary>, <param>, <returns> i <exception> sprawiają, że gdy INNY programista w Visual Studio zacznie pisać ObliczCeneZRabatem(, zobaczy automatyczną podpowiedź z opisem parametrów i tym, co metoda zwraca — BEZ potrzeby otwierania i czytania jej implementacji.
Komentarz // Zaokrąglamy do pełnych groszy... wymóg zgodności z fakturami VAT to PRZYKŁAD dobrego komentarza "zwykłego" (nie XML doc) — tłumaczy DLACZEGO w kodzie jest akurat Math.Round(..., 2), czego samo spojrzenie na kod by nie ujawniło (ktoś mógłby pomyśleć, że to dowolny wybór, a to w rzeczywistości wymóg biznesowy/prawny).
Ćwiczenie samodzielne
Wybierz dowolną metodę napisaną we wcześniejszych lekcjach (np. WyznaczPierwsze z lekcji 2) i dodaj do niej pełny komentarz XML doc (<summary>, <param>, <returns>). Sprawdź w Visual Studio, czy IntelliSense pokazuje Twój opis przy wywoływaniu tej metody z innego miejsca w kodzie.
Zadania do pracy własnej
Napisz krótki plik README.md (w Markdown) dla dowolnego projektu z tego kursu (np. Serwis ogłoszeniowy) — zawrzyj: nazwę projektu, krótki opis co robi, listę wymaganych technologii, kroki uruchomienia lokalnie.
Napisz fragment instrukcji użytkownika (3-4 kroki, językiem zrozumiałym dla osoby NIETECHNICZNEJ) dla funkcji "dodawanie ogłoszenia" z projektu Serwis ogłoszeniowy — bez żadnego żargonu programistycznego.
Napisz dokumentację wdrożenia (dla administratora) dla aplikacji ASP.NET Core + Angular z działu Aplikacje webowe — uwzględnij: wymagania systemowe (.NET, Node.js), kroki budowania (ng build, dotnet publish — patrz lekcja o wdrażaniu), konfigurację connection stringa do bazy danych, i listę portów, które muszą być otwarte.
Typowe błędy
Komentarze opisujące CO kod robi, zamiast DLACZEGO (np. // pętla for nad zwykłą pętlą for) — takie komentarze nie wnoszą żadnej wartości i tylko zaśmiecają kod; dobrze nazwane zmienne/metody powinny wystarczyć do zrozumienia CO się dzieje.
Nieaktualizowanie dokumentacji po zmianie kodu — komentarz albo README opisujący STARE zachowanie metody jest GORSZY niż brak dokumentacji, bo wprowadza w błąd; dokumentację trzeba traktować jako część kodu, aktualizowaną RAZEM z nim.
Mieszanie dokumentacji dla różnych odbiorców w jednym dokumencie — instrukcja użytkownika pełna technicznego żargonu (connection string, API, DTO) jest bezużyteczna dla przeciętnego użytkownika końcowego, a dokumentacja wdrożenia napisana "po ludzku" bez konkretnych komend jest bezużyteczna dla administratora.
Nawiązanie do egzaminu zawodowego
To pokrycie INF.04.8.2 ("dokumentuje tworzoną aplikację: komentarze w kodzie, dokumentacja kodu, dokumenty pomocy, instrukcja użytkownika, dokumentacja wdrożenia, dokumentacja z testów"). Razem z testami (lekcje 1-7) dokumentacja domyka pełny obraz "dojrzałego" podejścia do tworzenia oprogramowania, które egzamin INF.04 wprost premiuje. W kolejnej lekcji zobaczysz, jak zautomatyzować część tego procesu — automatyzację testów.