Rozważmy taki kawałek kodu:
[csharp]
public double CaclulateField(double width, double height){
return width * height;
}
[/csharp]
Podpowiadanie składni dla niego wygląda tak:
Ogólnie szału nie ma. Można się domyśleć co robi funkcja i co podać w parametrach jednak czasem chciało by się mieć pięknie opisane parametry – szczególnie gdy tworzymy publiczne api, które będzie wykorzystywane na zewnątrz – poza naszym działem, firmą, przez osoby, z którymi nie współpracujemy bezpośrednio i nie możemy szybko wytłumaczyć co autor miał na myśli. Wtedy chciało by się mieć takie podpowiadanie:
Lub nawet takie:
czyli od razu mówiące o wyjątkach.
Żeby to uzyskać, wystarczy początkową metodę opisać w poniższy sposób:
[csharp]
/// <summary>
/// Metoda obliczania pola kwadratu dla podanej
/// wysokości i szerokości
/// </summary>
/// <param name="width">szerokość</param>
/// <param name="height">wysokość</param>
/// <returns>pole kwadratu o zadanych bokach</returns>
/// <exception cref="NegativeValueException">
/// </exception>
public double CalculateField(double width, double height)
{
return width*height;
}
[/csharp]
Takie rozwiązanie ma jedną zasadniczą wadę, zmieniając kod a nie zmieniając komentarzy w szczególności dodają nowe parametry lub zmieniając znaczenie starych stawiamy przyszłego użytkownika takiego api w sytuacji gdy intelisense go okłamuje. No i biedny musi sam badać co zrobi nasz wspaniale opisany kod. Ten problem jest zresztą typowy dla wszystkich komentarzy. Kod się zmienia, ewoluuje a komentarz zostaje i w skrajnych wypadkach może być zupełnie nieadekwatny do tego co opisuje a częściej po prostu nieaktualny.
Rozwiązaniem na to są testy jednostkowe. TAK normalne testy jednostkowe. Jeżeli chcemy ułatwić życie innym to stwórzmy serię testów jednostkowych wykorzystujących to nasze API na wszelkie przewidziane przez na sposoby . Umieśćmy je w projekcie examples czy podobnie i wtedy użytkownik – inny programista (a jakże) ucieszy się niezmiernie. Będzie mógł uruchomić kawałek kodu i zobaczyć jak działa, będzie mógł go zdebugwać, poeksperymentować z nim a i my sami zaoszczędzimy sobie czasu, bo jeśli zmienimy api to testy przestaną się kompilować i/lub uruchamiać więc natychmiast będziemy mieli informację zwrotną na temat tego co i gdzie zmienić – koniec z przeglądaniem dokumentacji “papierowej” w poszukiwaniu jakiś zmian. Pomyślcie o innych – niech nikt już nie musi się borykać z nieaktualnymi przykładami w jakimś zapomnianym CHMie czy na niezaktualizowanej stronie.
