Dokumentacja

Pisanie dokumentacji jest czynnością, która idzie w pierwszym szeregu obok API. Zamierzeniem tego dokumentu nie jest opisywanie wszystkich drobnostek "wewnętrznych" klasy, ale jest nim pomoc innym programistą, w efektywnym jej używaniu. AEwiczenia w pisaniu dokumentacji pomagają w generalnym procesie projektowania, więc warto poświęcić na ten proces chwilę czasu, nawet jeśli danego kodu będziemy używać tylko my sami.

Informacjami, które powinny tam znaleźć są: ogólny opis - co dana klasa robi - oraz cele poszczególnych funkcji - argumenty, które przyjmuje, a także wartości, które zwraca (mam na myśli typy zmiennych). Najważniejsze jest, aby te informacje były przydatne dla innych programistów. Nie muszą oni wiedzieć co dokładnie robimy "za sceną", ale istotne jest, aby orientowali się jak korzystać z API klasy.

Jest wiele narzędzi, których możemy użyć, aby wygenerować czytelną dokumentacje na podstawie kodu źródłowego. W serwisie Devshed opublikowano ciekawy artykuł pt.: Writing Self Documenting Code ("Pisanie samo-dokumentującego się kodu"). Niektóre aplikacje wspomagające PHP to: Doxygen, PHPDoc (napisany w PHP, temat powyższego artykuły, na obecną chwilę część repozytorium PEAR), alternatywny PHP Documentor (również napisany w PHP, sam posiada doskonałą dokumentację), inne narzędzie noszące nazwę PHP Doc (używany w projekcie Eclipse, jest to odpowiednik Javadoc) oraz eZ phpdoc (napisany w Perlu, warte odnotowania jest to, że od wersji 3.0 eZ systems używa Doxygen).