Dokumentowanie kodu — komentarze XML i instrukcja
Program, którego nikt poza autorem nie potrafi uruchomić, jest gotowy tylko w połowie. Ta lekcja jest o drugiej połowie — i o tym, czego wymaga się na egzaminie zawodowym.
Czego się dziś nauczysz
- Opiszesz metodę komentarzem XML z parametrami, wynikiem i wyjątkami
- Włączysz generowanie pliku dokumentacji w projekcie
- Odróżnisz komentarz potrzebny od komentarza powtarzającego kod
- Napiszesz README dla programisty i instrukcję dla użytkownika
- Przygotujesz raport z testów w postaci tabeli przypadków
Przygotowanie: lekcje 01–56. Przewidywany czas: 45–90 minut z zadaniami. Przykłady wymagają .NET 8 lub nowszego, z włączonymi ImplicitUsings i Nullable.
Komentarze dokumentacyjne
Zwykły komentarz // widzi tylko ten, kto czyta plik. Komentarz zaczynający się od trzech ukośników trafia do podpowiedzi edytora i do pliku dokumentacji.
/// <summary>
/// Oblicza srednia arytmetyczna ocen.
/// </summary>
/// <param name="oceny">Tablica ocen z zakresu 1-6. Nie moze byc pusta.</param>
/// <returns>Srednia jako liczba rzeczywista.</returns>
/// <exception cref="ArgumentException">
/// Gdy tablica jest pusta albo rowna <c>null</c>.
/// </exception>
public static double Srednia(int[] oceny)
{
// ...
}Gdy ktoś napisze Oceny.Srednia(, edytor pokaże mu ten opis razem z listą parametrów. Nie musi otwierać twojego pliku ani zgadywać, co się stanie przy pustej tablicy.
| Znacznik | Do czego |
|---|---|
<summary> | jedno–dwa zdania: co metoda robi. Nie jak. |
<param name="x"> | znaczenie parametru i dopuszczalne wartości |
<returns> | co metoda zwraca, także w przypadkach szczególnych |
<exception cref="T"> | kiedy metoda zgłasza wyjątek danego typu |
<remarks> | uwagi dodatkowe, ograniczenia, wydajność |
<example> | krótki przykład użycia |
<c> i <code> | fragment kodu w treści opisu — krótki i wielowierszowy |
Żeby dokumentacja powstała jako plik XML, dopisz do pliku projektu:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>Komentarz, który kłamie, jest gorszy niż jego brak
Opis <summary> zostaje przy metodzie po zmianie jej działania i po cichu wprowadza w błąd. Przy każdej poprawce metody przeczytaj jej opis. Jeśli nie zamierzasz go utrzymywać — nie pisz go.
Komentarz, który warto napisać
Komentarz nie ma powtarzać kodu. Ma powiedzieć to, czego z kodu nie widać: dlaczego.
| Zamiast | Napisz |
|---|---|
i++; // zwieksz i o jeden | nic — to widać |
// petla po tablicy | nic — to też widać |
// limit 100 wynika z rozmiaru arkusza egzaminacyjnego | |
// sortujemy kopie, bo oryginalna kolejnosc jest potrzebna w raporcie | |
// TryParse zamiast Parse: uzytkownik czesto wkleja spacje |
Najlepszy komentarz to dobra nazwa. Zmienna licznikBlednychWierszy nie potrzebuje wyjaśnienia, którego wymaga x2 (lekcja 05).
Trzy dokumenty przy projekcie
Podstawa programowa wymaga od technika programisty nie tylko kodu, ale i dokumentacji. W praktyce chodzi o trzy różne teksty dla trzech różnych czytelników.
| Dokument | Dla kogo | Co zawiera |
|---|---|---|
| README | programista, który dostanie projekt | do czego służy program, wymagania (.NET 8), jak zbudować i uruchomić, jak puścić testy, układ folderów |
| Instrukcja użytkownika | osoba, która ma programu używać | co program robi, opis każdej opcji menu, format wprowadzanych danych, opis komunikatów o błędach, typowy scenariusz krok po kroku |
| Raport z testów | nauczyciel, zespół, klient | lista przypadków testowych, dane wejściowe, wynik oczekiwany, wynik otrzymany, status oraz opis znalezionych błędów |
# Turniej szkolny
Konsolowa obsluga turnieju: dodawanie uczestnikow, ranking, zapis raportu.
## Wymagania
- .NET 8 lub nowszy
## Uruchomienie
dotnet run --project Turniej.Konsola
## Testy
dotnet test
## Format pliku raportu
Kazdy wiersz: `imie;punkty`, kodowanie UTF-8.
Punkty: liczba calkowita 0-100. Wiersze niepoprawne sa pomijane z komunikatem.Raport z testów zapisuj w trakcie, nie po
Tabelka z kolumnami przypadek / dane / oczekiwane / otrzymane / status wypełniana przy każdym sprawdzeniu zajmuje minutę. Odtwarzanie jej z pamięci dzień przed oddaniem projektu zajmuje godzinę i zwykle wychodzi nieprawdziwa.
Na co uważać
| Zapis | Problem |
|---|---|
| Komentarz powtarzający kod | Zajmuje miejsce i starzeje się szybciej niż kod. |
<summary> opisujący implementację | Po refaktoryzacji przestaje być prawdziwy. Opisuj zadanie, nie sposób jego wykonania. |
| Zakomentowany stary kod | Do tego służy system kontroli wersji. W pliku zostaje śmieć, którego nikt nie odważy się usunąć. |
<param> z nieistniejącą nazwą | Ostrzeżenie kompilatora CS1572 i mylące podpowiedzi. |
| Instrukcja użytkownika pisana językiem programisty | Użytkownik nie wie, czym jest wyjątek ani tablica. Pisz o tym, co widzi na ekranie. |
| Brak opisu formatu danych | Najczęstsze pytanie do każdego programu konsolowego brzmi „a jak mam to wpisać?”. |
Zadania
Dodaj komentarze XML do trzech dowolnych metod z wcześniejszych lekcji: <summary>, <param> i <returns>. Sprawdź w edytorze, czy podpowiedź się pojawia.
Uzupełnij dokumentację metody Srednia o znacznik <exception> dla każdego wyjątku, który może zgłosić.
Włącz GenerateDocumentationFile, zbuduj projekt i znajdź powstały plik XML. Otwórz go i porównaj z komentarzami w kodzie.
Weź własny program z dowolnej wcześniejszej lekcji i usuń wszystkie komentarze powtarzające kod. Te, które zostaną, przepisz tak, żeby odpowiadały na pytanie „dlaczego”.
Napisz README dla jednego ze swoich programów: opis, wymagania, uruchomienie, format danych, znane ograniczenia. Daj do przeczytania koledze i popraw to, o co zapytał.
Dla projektu końcowego przygotuj README, instrukcję użytkownika i raport z testów w postaci tabeli. Instrukcja ma opisywać wszystkie opcje menu i wszystkie komunikaty o błędach, jakie może zobaczyć użytkownik.
Co trzeba zapamiętać
- Komentarz
///trafia do podpowiedzi edytora i do pliku dokumentacji XML. <summary>,<param>,<returns>i<exception>wystarczą do opisania metody.- Komentarz w kodzie ma tłumaczyć dlaczego, a nie powtarzać, co robi instrukcja.
- Dobra nazwa zastępuje komentarz; zły komentarz jest gorszy niż jego brak.
- Projekt oddajemy z README dla programisty i instrukcją dla użytkownika — to dwa różne teksty.
- Raport z testów wypełniaj na bieżąco: przypadek, dane, wynik oczekiwany, otrzymany, status.
Dokumentacja: Microsoft Learn — temat tej lekcji.