[PHP] Podstawy pisania czytelnego kodu

Piszę ten artykuł, ponieważ zauważyłem, że naprawdę wiele początkujących osób nie zwraca na to najmniejszej uwagi.

Zacznijmy od początku. Być może zastanawiasz się dlaczego trzeba dbać o czytelność kodu?

Podstawową zasadą jaką powinieneś przyjąć jest to, że z kodem będą pracować także inni ludzie, a nie tylko Ty. Może do tego dojść choćby przy udzielaniu pomocy na forum lub pisania projektu przez kilka osób. Wtedy czytelność kodu staje się naprawdę ważna, choć uwierz mi, że w momencie kiedy napiszesz naprawdę dużo kodu, bez zwracania uwagi na jego czytelność, to sam bez problemu się w nim pogubisz.

Komentarze

Po to bozia dała chyba praktycznie w każdym języku programowania możliwość komentowania kodu, żeby z niej korzystać. Jak pewnie wiesz, w PHP mamy 3 rodzaje komentarzy.

// komentarz jednolinijkowy

# inny komentarz jednolinijkowy (wywodzący się z Perla)

/* komentarz
wielolinijkowy
może się ciągnąć
w nieskończoność */

Pamiętaj o tym, aby wybrać jeden sposób tworzenia komentarzy jednolinijkowych. W przeważającej większości używa się komentarza //. Komentarze rozpoczynające się od znaku hash #) są już prawie niespotykane, choć część skryptów wykorzystuje je np. do oznaczania sekcji w plikach konfiguracyjnych.

Wcięcia

Ośmielę się napisać, że jest to najważniejsza kwestia jeśli chodzi o czytelność kodu. Porównaj te 2 przykładowe listingi.

if ($petla == true)
{
foreach ($zmienne as $zmienna) {echo strtolower($zmienna); }
} else {
echo 'nie ma pętli';
}

versus

if ($petla == true) { // w tym wypadku lepiej po prostu if ($petla)
    foreach ($zmienne as $zmienna) {
        echo strtolower($zmienna);
    }
}

else {
    echo 'nie ma pętli';
}

Z ułożenia kodu pokazanego na drugim listingu wynika dużo korzyści. Przede wszystkim na pierwszy rzut oka widać, że mamy do czynienia z dwoma warunkami, z czego w pierwszym z nich zawarta jest pętla foreach. Ważne jest to, aby „głębokość” wcięć przy każdym kolejnym poziomie zagnieżdżenia była jednakowa w całym skrypcie.

Nazewnictwo

Kolejna bardzo ważna kwestia. Tutaj liczy się zarówno sposób zapisywania nazw zmiennych, funkcji, klas, metod itd. jak i język w jakim je zapisujemy. Bardzo wielu początkujących zapisuje zmienne w języku polskim. Ponownie przyjrzymy się dwóm przykładom kodu.

$tablica = array(1, 3, 66);
$napis = ‘To prawda’;

if (count($tablica) == 3)
    echo $napis;
$array = array(1, 3, 66);
$text = ‘To prawda’;

if (count($array) == 3)
    echo $text;

Przyznacie chyba, że dużo logiczniej brzmi sekwencja if count array == 3, echo text niż if count talica == 3, echo napis. Skoro instrukcje oraz wbudowane funkcje w języku PHP są w języku angielskim, to nie ma najmniejszego sensu miksować tego z innym językiem i robić bałaganu.

Tutaj zrobię też krótką dygresję do osób, które w tym momencie pomyślały „ale ja nie znam angielskiego. Nie będę się go uczyć, tylko po to, żeby nazwać kilka zmiennych”. Otóż angielski w każdym języku programowania jest językiem podstawowym. Pomijając to, o czym już mówiłem, czyli to, że wszystkie wbudowane instrukcje i funkcje są nazwane po angielsku, niezaprzeczalnym faktem jest, że dużo więcej materiałów na temat programowania jest właśnie w języku angielskim (choćby większość dokumentacji PHP).

Drugą kwestią jest to jak zapisujemy nazwy zmiennych, klas, funkcji, metod itd. Oto niektóre ze sposobów, przedstawię je na przykładzie zmiennej  o nazwie simple var.

echo $simplevar; // totalnie nieczytelne
echo $simple_var ; // metoda pierwsza
echo $simpleVar; // metoda druga (tzw. camelCase)

Oczywiście, że poza tym mamy jeszcze wiele mniej lub bardziej stosowanych sposobów nazewnictwa – chociażby notację węgierską, jednak temu tematowi można by poświęcić spokojnie cały wpis, a ja chciałem jedynie pokazać przykładowe sposoby nazewnictwa.

Zaletami nazywania w stylu $simple_var, jest to, że wszędzie stosowane są tylko małe litery, a PHP rozróżnia je, jeśli chodzi o nazwy zmiennych.

Podsumowanie

Ten artykuł omawia zaledwie zalążek tematu, jednak być  może po jego przeczytaniu łatwiej będzie Wam tworzyć kod łatwiejszy w zarządzaniu. Pamiętajcie, że ważne jest bycie konsekwentnym w decyzjach (zresztą nie tylko w programowaniu…). Kiedy już zdecydujecie się np. na pisanie zmiennych po angielsku, metodą camelCase, to trzymajcie się tego przez cały skrypt, nie róbcie bałaganu i nie utrudniajcie roboty, tym, którzy będą czytać kod po Was.

9 komentarzy do “[PHP] Podstawy pisania czytelnego kodu

  1. Nie wyczerpałeś tematu. Wszystko co napisałeś rozbija się o standardy kodowania. Ja używam haszu w komentarzach, plikach i nie tylko :) Przykłady z nazewnictwem są takie same czy mi się wydaje?

    Jedyne co potrafię zrozumieć jeżeli chodzi o polskie nazewnictwo to przypadek kiedy to zamknięty projekt polski.

    Zajrzyj na tureckie fora programistyczne (szczególnie webmasterka) i dojdziesz do wniosku, że oni używają tylko tureckiego w nazewnictwach… No bo przecież angielskiego to nie łaska się nauczyć, a może to umyślny zabieg?

    A co do formatowania kodu to są odpowiednie parsery do konwersji kodu na odpowiedni „standard kodowania”. Tak czy siak bardzo ważna sprawa jak pracuje się w grupie.

    • Sobak pisze:

      Oczywiście, że nie wyczerpałem tematu. Jak mówi sam tytuł, są to tylko podstawy ;) Rozgraniczyłbym jednak treść tego artykułu od standardów kodowania. Standardy kodowania powstają najróżniejsze, a to co jest tutaj to podstawy uniwersalne dla każdego z nich. Różne jest wykonanie, ale założenia są identyczne – kod utrzymany w porządku, pisany konsekwentnie w jeden sposób i łatwy do analizy.

  2. Soanvig pisze:

    Ja mam nawyk, żeby nie śmiecić sobie kodu niepotrzebnymi klamerkami, np. kiedy dla if-a mam tylko jedną komendę do wykonania to używam:

    if(blahblah) kasztany;
    else kartfole;

    Też dobre, zaoszczędza się miejsca i oczojeb**** klamerek.

  3. Sobak pisze:

    Ja różnie z tymi klamerkami, ale ostatnio generalnie skłaniam się ku używaniu klamerek wszędzie. A teraz wytłumacz mi: jak klamry mogą być oczojebne? :D Ponadto większość edytorów udostępnia możliwość zmiany kolorowania niektórych elementów.

  4. ktosZNetuPrzezGoogleTrafil pisze:

    wszystko fajnie, tylko jednak nie sprawdziłeś tekstu dobrze i uczysz złych nawyków…:

    $array = array(1, 3, 66);
    $text = ‘To prawda’;

    if (count($array) == 3)
    echo $text;

    czemu nie ma wcięcia przy echo $text? ;)

    Poza tym czemu:
    if ($petla == true)
    a nie krótko:
    if ($petla)
    ?
    ew. if ($petla === true)
    jeśli zależy nam na kontroli typów.

    • Sobak pisze:

      Poprawiłem, pierwszy błąd dotyczący wcięć wynikał niestety ze skopanej wtyczki do kolorowania kodu.

      Drugi był moim błędem lub też po prostu chęcią uczynienia kodu jak najłatwiejszego do przeczytania przez początkujących, z tego samego powodu w pierwszych listingach zmienne są pisane po polsku, mimo, że chwilę później tego odradzam ;)

      Pozdrawiam.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *