Komentarze w PHP pozwalają na dokumentację skryptu wewnątrz kodu. Przydaje się to, gdy ktoś inny chce zrozumieć działanie skryptu lub nawet gdy jego autor po dłuższej przerwie chce powrócić do kodu. Poniżej zaprezentowana jest konstrukcja komentarza w stylu języka C.
<?php /* treść komentarza */ ?>Taki styl komentarza może obejmować jeden lub więcej wierszy.
W PHP można również używać komentarzy jednowierszowych, zarówno w stylu C++:
<?php $a = $a + $b; // treść komentarza ?>jak i w stylu skryptów powłoki:
<?php $a = $a + $b; # treść komentarza ?>W obu powyższych stylach wszystko, co następuje po symbolu komentarza (// lub #), do końca wiersza jest traktowane jako komentarz i ignorowane przez interpreter PHP (przeglądarka nigdy nie widzi kodu PHP, bo wykonuje się on na serwerze).
Nie można zagnieżdżać komentarzy – czyli umieszczać jednego komentarza wewnątrz innego.
Komentarze dokumentacyjne PHPDoc
Osobną, bardzo praktyczną odmianą komentarza blokowego jest komentarz dokumentacyjny, zaczynający się od /**. Opisuje on funkcję lub klasę w ustalonym formacie PHPDoc, dzięki czemu rozumieją go edytory: podpowiadają typy parametrów i ostrzegają przed błędnym wywołaniem.
<?php
/**
* Liczy cene brutto na podstawie ceny netto.
*
* @param float $netto cena netto produktu
* @param float $stawka stawka VAT, np. 0.23
* @return float cena brutto
*/
function brutto(float $netto, float $stawka = 0.23): float {
return $netto * (1 + $stawka);
}
?>Najczęściej używane znaczniki to @param (opis parametru), @return (co funkcja zwraca) i @throws (jakie wyjątki może rzucić). Nawet jeżeli nie generujemy z tego dokumentacji, sam edytor odwdzięczy się lepszymi podpowiedziami.
Szybkie komentowanie w edytorze
W praktyce komentarzy rzadko używa się tylko do opisów. Podczas szukania błędu często „wyłącza się” fragment kodu, komentując go. Każdy sensowny edytor robi to jednym skrótem: zaznaczamy linie i wciskamy Ctrl + / (VS Code i PhpStorm, na Macu Cmd + /). Ten sam skrót zdejmuje komentarz.
Kiedy komentarz pomaga, a kiedy szkodzi
Na koniec kwestia dobrych praktyk, bo komentarze bywają też pułapką. Dobry komentarz wyjaśnia DLACZEGO kod robi to, co robi (obejście błędu w bibliotece, wymaganie biznesowe, nieoczywista decyzja). Zły komentarz opisuje to, co i tak widać:
<?php
$licznik++; // zwieksza licznik o 1 <- zly: powtarza kod
$cena *= 1.08; // stawka 8% dla uslug transportowych (ustawa o VAT) <- dobry: wyjasnia "dlaczego"
?>Największym grzechem jest komentarz nieaktualny, który opisuje kod sprzed zmian: czytelnik ufa komentarzowi bardziej niż kodowi i traci czas na szukanie błędu we właściwym miejscu. Zasada jest prosta: zmieniasz kod, zmień też komentarz obok, a jeżeli komentarz tylko powtarza kod, usuń go.



// brak komentarzy — bądź pierwszy