Praktyka Design by Contract ułatwia dokumentowanie pisanego kodu.

Dokumentowanie kodu to zajęcie, którego nie lubi żaden programista, starając się zepchnąć je na ostatni etap pracy nad projektem. Pisanie komentarzy do kodu ułatwia mało znana praktyka Design by Contract (DbC), stanowiąca integralną część również języka Eiffel.

Kod z dokumentacją

DbC to sformalizowana metoda pisania komentarzy w taki sposób, aby zawrzeć w nich specyfikację kodu. Wiąże się to z opracowaniem tzw. kontraktów, opisujących wymagania stawiane kodowi. Przykładowy kontrakt zawiera opis warunków wejściowych, które powinny być spełnione przed wy- wołaniem metody; wyników, których oczekujemy w efekcie wykonania metody, oraz stwierdzeń (assertions) co do warunków, które metoda musi spełniać w określonych punktach wykonania.

Innymi słowy, kontrakty opisują założenia programisty piszącego kod oraz założenia systemu odnośnie do konkretnej części kodu. Dla przykładu, jeśli programista wie, że określona zmienna nie może przyjmować wartości nieokreślonej (null) ani być ujemna, powinien to zapisać w kontrakcie.

Z punktu widzenia szefa zespołu, DbC rozwiązuje odwieczny problem dokumentowa- nia kodu i zapewnia możliwość automatycznego sprawdzenia, czy napisana dokumentacja nie zawiera błędów lub nie jest sprzeczna wewnętrznie. Kontrakty DbC są pisane w sformalizowanej postaci, wystarczy więc opracować lub zakupić gotowe narzędzie, czytające zarówno kod, jak i komentarze i stwierdzające ich brak lub niekompletność. W zespołach nie używających DbC jedyna możliwość sprawdzenia poprawności dokumentacji sprowadza się do jej żmudnej analizy i weryfikacji z kodem wiersz po wierszu.

Korzyści wynikające ze stosowania DbC są wymierne: koncepcje programowe znajdują się bezpośrednio w kodzie, kontrakty są łatwe do sprawdzenia, dokumentowany kod jest lepiej przystosowany do powtórnego wykorzystania, i zmniejsza się ryzyko wprowadzenia błędów w trakcie dokonywania zmian w kodzie, gdy ma się stały dostęp do specyfikacji.

Narzędzia ParaSoft

Firma ParaSoft wprowadziła na rynek 2 narzędzia przeznaczone do pracy z kodem Java, dokumentowanym za pomocą DbC Đ JTest i JContract. Pierwsze z nich służy do analizy i testowania statycznego kodu Java i ma upewnić programistę, że dana klasa lub komponent, które mają być włączone do aplikacji, są bezbłędne.

JTest automatycznie sprawdza, czy wszystkie klasy są zaopatrzone w odpowiednie znaczniki DbC, tworzy na podstawie specyfikacji scenariu- sze testowe metod, usuwa ewentualne pogwałcenia warunków wstępnych i wszystkie wyjątki udokumentowane w kontrakcie. Pokazuje również wszystkie błędy znalezione w module.

JContract służy do sprawdzania klasy lub komponentu w trakcie działania. Narzędzie rekompiluje kod źródłowy Java, uzupełniając go informacjami zawartymi w specyfikacji (dotyczącymi sposobu użycia klasy i jej działania), i uruchamia go, by w trakcie działania sprawdzić wszystkie niedotrzymania kontraktu (informacja o nich może być zapisywana w pliku).

Znaczniki DbC

Znaczniki DbC umieszcza się w kodzie Java w formie standardowych komentarzy. Ich postać nie jest zdefiniowana przez standardy Java, ale jest specyficzna dla języka Eiffel i narzędzi firmy ParaSoft.

Znacznik	Cel
@pre	Warunek wstępny, który musi spełniać wywołanie metody.
@post	Warunek, który musi spełnić metoda po wykonaniu.
@assert	Wyrażenie Boole'owskie na temat stanu programu. Jest wykonywane w miejscu umieszczenia w programie. Niespełnienie znacznika oznacza błąd w metodzie.
@invariant	Warunek wstępny, mający zastosowanie do wszystkich metod w klasie.
@exception	Znacznik wskazujący na to, że program powinien wywołać wyjątek (exception).
@concurrency	Znacznik pokazujący warunki równoczesności dla wywołania metody.
@verbose	Pozwala na dodanie werbalnych stwierdzeń do kodu.