/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?)

W drugiej części napi­szę co nieco na temat nazew­nic­twa klas i metod. Jak nazy­wać i czego unikać. Do tego na koniec dodam kilka zale­ceń Roberta C. Martina z Czystego Kodu [Gliwice : Helion, 2010].

Klasy

Skład­ni­kiem nazwy klasy nie powi­nien być żaden czasow­nik. Mało tego, nie powi­nien to być również frag­ment nazwy imple­men­to­wa­nego inter­fejsu lub klasy nadrzęd­nej. Stosu­jemy Camel­Case począw­szy od dużej litery. Zgod­nie z Czystym Kodem lepsza jest dłuż­sza nazwa klasy/metody niż krót­sza plus komen­tarz wyjaśniający.

W przy­padku progra­mo­wa­nia zgod­nego z Zend nale­ża­łoby nazwę poroz­dzie­lać podkreśl­ni­kami prowa­dzą­cymi przez struk­turę kata­lo­gów do pliku zawie­ra­ją­cego kod klasy, np. Zend_File_Transfer_Adapter_Http

Pola klas

Krót­kie nazwy zmien­nych typu $i, $j dopusz­czalne są tylko w pętlach lub zmien­nych lokal­nych. Pola klasy również nazy­wamy zgod­nie z Camel­Case z tym, że rozpo­czy­namy od małej litery. Warte zwró­ce­nia uwagi jest to, że pola i metody prywatne w klasie rozpo­czy­nają się od znaku podkre­śle­nia, dzięki czemu od razu widać czy odwo­łu­jemy się do metody publicz­nej czy prywatnej.

Nazwę stałych tworzymy wyłącz­nie za pomocą dużych liter i podkreśl­ni­ków. Poni­żej przy­kład wzięty z Zend_Filter
const CHAIN_APPEND  = 'append';
const CHAIN_PREPEND = 'prepend';

Metody

Przy­jęło się kilka konwen­cji jeżeli chodzi o nazew­nic­two metod. Metody muta­to­rów (tzw. settery) i akce­so­rów (tzw. gettery), czyli usta­wia­jące i pobie­ra­jące zmienne obiektu tworzymy poprzez setNazwa($nazwa) i getNazwa().

Innymi powszech­nie znanymi meto­dami są isNazwa() i hasNazwa(). Czyli czy obiekt jest czymś lub czy obiekt ma jakąś własność. Muszą one zwra­cać wartość typu boolean.

Pamię­tamy o tym, że PHP oferuje ogra­ni­czone typo­wa­nie para­me­trów. A w tym zakre­sie, jakie oferuje należy je stoso­wać, czyli możemy wymu­sić, że przyj­miemy tylko obiekt okre­ślo­nego typu lub imple­men­tu­jący okre­ślony inter­fejs, czyli np. metoda(Trąbka $trąbka) wymusi nam, że obiekt musi być typu Trąbka. Niestety typów prostych typu int czy bool nie możemy wymu­sić. Zamiast tego pamię­tamy zazna­czyć typ w dokumentacji.

W Zend powszech­nie stoso­wany jest rozdział tworze­nia obiektu od jego inicja­li­za­cji za pomocą metody init(). Jeżeli na etapie tworze­nia obiektu coś się wysy­pie i konstruk­tor wyrzuci wyją­tek, obiekt nie zosta­nie utworzony.

Poni­żej kilka zale­ceń z Czystego Kodu doty­czące metod:

• metoda powinna zajmo­wać do ok. 20 linii kodu,
• powinna wyko­ny­wać jedną operację,
• metoda bez para­me­trów jest zawsze lepsza niż z jednym,
• dopusz­czalne jest do 3 para­me­trów w meto­dzie; jeżeli jest więcej tzn. że gdzieś popeł­ni­li­śmy błąd,
• para­metr true/false najczę­ściej ozna­cza, że metoda robi dwie różne rzeczy i najle­piej rozdzie­lić ją na dwie osobne,
• doda­wa­nie „na pałę” do każdego pola prywat­nego settera i gettera mija się z celem (po co było usta­wiać zmienną na private skoro i tak można robić z nią co się chce poprzez settery/gettery),
• bloków try/catch nie należy mieszać z normal­nym prze­twa­rza­niem, należy je wydzie­lić do osob­nych funk­cji jako mają­cych za zada­nie obsługę błędów

Na stro­nie Zend Frame­work macie podane konwencje/standardy doty­czące forma­to­wa­nia kodu, nazew­nic­twa i doku­men­ta­cji. Chciał­bym pewne rzeczy rozsze­rzyć w opar­ciu o własne obser­wa­cje kodu ZF i zale­ce­nia twórców/ekspertów (głów­nie z ich blogów). Nie będę oczy­wi­ście bawił się w tłuma­cza. Mam nadzieję, że ten 3 częściowy wpis się komuś przyda. Dzielę go z braku czasu…

1. Forma­to­wa­nie kodu

• każda klasa w osob­nym pliku, bez znaku kończą­cego skrypt ?>
• nie wolno używać skró­co­nej formy <? ?> lub <% %>
• wcię­cia mają liczyć 4 spacje, bez tabu­la­to­rów (mądrzej­sze edytory same zamie­niają taby na spacje)
• długość poje­dyn­czej linii kodu powinna wyno­sić poni­żej 80 znaków, w pewnych okolicz­no­ściach dopusz­czalne jest więcej, do 120 znaków (abso­lutny limit)
• nazwa klasy zgodna ze struk­turą kata­lo­gów poprze­dzie­la­nych podkreśl­ni­kiem, czyli np. class Spiechu_Captcha, za to plik w tym przy­padku będzie się nazy­wał Captcha.php (jeżeli nie progra­muję w ZF to tego nie używam, ponadto moje pliki kończą się na .class.php, np. captcha.class.php
• bez spacji pomię­dzy nazwą funk­cji a para­me­trami, np. function getStringFormatted($string), za to jeżeli jest kilka para­me­trów, to wtedy po prze­cinku jedna spacja
• jedna spacja po struk­tu­rach kontro­l­nych typu if else switch i pętlach typu for foreach
• spacja przed i po znakach przypisujących/arytmetycznych/logicznych typu = .= + - / % == && ||
• tzw. one true brace, czyli po dekla­ra­cji klasy i po para­me­trach metod nawias klam­rowy powi­nien zostać prze­nie­siony do nowej linii, za to przy wszel­kich ifach czy forach nie (przy­znaję się bez bicia, nie stosuję OTB )
• jeżeli istnieje możli­wość wymu­sze­nia typu para­me­tru, stoso­wać to (przy­po­mi­nam, że PHP od wersji 5.3 umoż­li­wia zapis function metoda(array $tablica) {coś tam} )
• używać „podwój­nych pazur­ków” tylko wtedy kiedy to jest konieczne (czyli gdy wsta­wiamy coś ze zmien­nej w locie), a jeżeli już to zawsze używać zapisu w nawia­sach klam­ro­wych, np. $s = "mój kot nazywa się {$kot}";
• jeżeli jest to możliwe, tablica powinna zaczy­nać się od warto­ści 0 $tablica[0]
• jeżeli nasz switch prze­wi­duje wartość default, musi być umiesz­czony jako ostatni (z breakiem!)

Tyle na dzisiaj. Jeżeli coś sobie przy­po­mnę lub wyczy­tam mądrego, zaktu­ali­zuję wpis.