/home/Śpiechu->Blog

Dzisiaj ostatni wpis doty­czący progra­mo­wa­nia zgod­nego z Zend. Będzie mowa o doku­men­ta­cji. Sporo infor­ma­cji będzie pocho­dziło z Czystego Kodu [dalej CK].

Przede wszyst­kim bloki doku­men­ta­cji muszą być zgodne z forma­tem phpDo­cu­men­tor, czyli
/**
* Coś tam dokumentuję...
*/
Współ­cze­sne IDE nie mają problemu z pilno­wa­niem zgod­no­ści z tym forma­tem. Wpisu­jesz /** naci­skasz Enter i masz ładny blok doku­men­ta­cji. Drugi sposób to wszyst­kim znane komen­ta­rze inline tworzone poprzez // przed treścią komentarza.

Zend Frame­work wymaga od nas umiesz­cze­nia doku­men­ta­cji w trzech miej­scach: na początku pliku, przed każdą klasą i przed każdą metodą. W doku­men­ta­cji ZF podano elementy, które powinny wcho­dzić w skład bloków. Nie będę tego powta­rzał. Zwrócę uwagę tylko na to, że typy para­me­trów i warto­ści zwra­cane przez funk­cje są również obligatoryjne.

Więk­szość komen­ta­rzy jest zła. Im szyb­ciej to przy­zna­cie tym lepiej. Zgod­nie z CK komen­ta­rze w więk­szo­ści służą nam do wytłu­ma­cze­nia się z błędów/niedoskonałości naszego kodu. Kod powi­nien być na tyle przej­rzy­sty, żeby komenty nie były wcale potrzebne. Czas poświę­cany na pisa­nie doku­men­ta­cji lepiej prze­zna­czyć na poprawki kodu. Łatwo rzucać slogany, trud­niej zrobić. Na pozio­mie jednej klasy często dobry efekt udaje się uzyskać poprzez rozpar­ce­lo­wa­nie długiej funk­cji na kilka mniej­szych i użycie bardziej opiso­wych nazw.

Wielce niewska­zana jest redun­dan­cja, czyli nadmia­ro­wość infor­ma­cji. Jeżeli nazwa funk­cji jest wystar­cza­jąco znacząca to rzeczy­wi­ście nie ma sensu powta­rzać tego samego. Raz, że uczy nas podświa­do­mego pomi­ja­nia doku­men­ta­cji (no bo po co coś czytać skoro jest oczy­wi­ste?), a dwa, że komen­ta­rze często nie nadą­żają za zmia­nami w kodzie. Stary koment smro­dzi bardziej niż jego brak O ile CK doty­czy Javy, a więc silnie typo­wa­nego języka (zawsze wiemy jakiego typu jest zmienna czy para­metr i co zwraca metoda), o tyle w PHP musimy używać doku­men­ta­cji do tego celu. Autor CK często daje znać, że jeżeli kod jest jasny to po co go komentować?

Sporo rzeczy robi za nas system kontroli wersji. Unikamy brzyd­kiego komen­to­wa­nia już niepo­trzeb­nego kodu oraz nie kusi nas wpro­wa­dza­nie dzien­nika zmian do komen­ta­rzy. W razie potrzeb oglą­damy sobie starą wersję pliku lub czytamy tekst z commitu. Osobi­ście używam Baza­ara do swoich projek­tów (mini­mum usta­wia­nia, dostępny pod Windows i Linux).

Dobry komen­tarz to np. wyróż­nie­nie rzeczy pozor­nie nieistot­nej, infor­ma­cja co jest jesz­cze do zrobie­nia (tzw. TODO) lub też przy­kład dopa­so­wa­nia wyra­że­nia regu­lar­nego. Przy­datne jest również stwo­rze­nie porząd­nego API publicz­nego (wyobra­ża­cie sobie napi­sać cokol­wiek w Javie bez API?)