Witaj, Gościu O nas | Kontakt | Mapa
Wortal Forum PHPEdia.pl Planeta Kubek IRC Przetestuj się!

Przewodnik po projektowaniu klas w PHP

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).

Informacje na podobny temat:
Wasze opinie
Wszystkie opinie użytkowników: (0)
Mentax.pl    NQ.pl- serwery z dodatkiem świętego spokoju...   
O nas | Kontakt | Mapa serwisu
Copyright (c) 2003-2022 php.pl    Wszystkie prawa zastrzeżone    Powered by eZ publish Content Management System eZ publish Content Management System