:~$ newsletter --subscribe
cat ~/artykuly/backend/komentarze-w-php.md

Komentarze w PHP

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
<?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
<?php $a = $a + $b; // treść komentarza ?>

jak i w stylu skryptów powłoki:

php
<?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
<?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
<?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.

udostępnij: ·
Jacek Trakul
Jacek Trakul · autor gościnny
Programista, od dziesięciu lat piszę o programowaniu i karierze w IT. więcej-o-mnie →
ls ~/artykuly/powiazane --limit 3
komentarze --count 0
rss dla komentarzy →

// brak komentarzy — bądź pierwszy

dodaj-komentarz

Komentarze są moderowane. Podane dane przetwarzamy wyłącznie w celu publikacji komentarza (polityka prywatności).