Kurs PHP – komentarze

Czym są komentarze?

Czy zdarzyło Ci się kiedyś czytać książkę/podręcznik i robić notatki na boku? Komentarze w programowaniu głównie służą po to, aby zrobić notatkę, którą język programowania nie będzie brał pod uwagę. Komentarze również są pomocne dla naszego IDE (zintegrowane środowisko programistyczne). Do IDE i komentarzach które pomagają IDE wrócę w innym wpisie. Na ten moment możesz skupić się na tym, że komentarze są Twoją notatką w kodzie, którą język programowania pomija podczas wykonywania.

Rodzaje komentarzy

Komentarz jedno-linijkowy

Komentarz jedno-linijkowy działa tak, że od podania // lub # do końca linii występuje komentarz, który PHP ignoruje podczas wykonywania.

<?php
$variable = 'TEST';   // KOMENTARZ 1
$variable = 'TEST';   # KOMENTARZ 2

Więc jeśli napiszesz coś takiego jak poniżej ⬇ to przypisanie 123 do zmiennej $variable nie nastąpi, ponieważ to się dzieje w komentarzu.

<?php
$variable = 'TEST';   // KOMENTARZ 1 $variable = 123;
echo $variable;

Jako ciekawostkę dodam, że ze swojego doświadczenia nie widziałam, aby # był wykorzystywany zbyt często. W projektach PHP zauważyłam, że dominuje // jako komentarz jedno-linijkowy.

Komentarz wielo-linijkowy

Jak sama nazwa wskazuje ten komentarz może się ciągnąć przez wiele linijek. Ma swój początek i koniec, więc tutaj nie obowiązuje zasada, że do końca linii. Komentarz taki zaczyna się od /* i kończy na */. Spójrz na poniższy przykład.

<?php
$variable = 'TEST';   /* pierwsza linia komentarza
druga linia komentarza */ $variable = 123; echo $variable;

Po wykonaniu tego kodu na ekranie wyświetli się 123. Ponieważ przypisanie wartości do zmiennej miało miejsce już po zamknięciu komentarza.

Swoją drogą to co napisałam powyżej jest kodem nieczytelnym, ale napisałam go, w celu lepszego zrozumienia jak działają komentarze wielo-linijkowe.

Dużo bardziej właściwą formą tego samego kodu jest poniższa wersja. Kod jest wtedy dużo bardziej czytelny. Dlaczego o tym wspominam? Ponieważ, jeśli przyjdzie Ci się rozwijać jako programista to czytelność kodu jest istotna. Wyobraź sobie, że ktoś ciągle pisze kod jak wyżej. Kod działa… ale to nie jest czytelne. W programowaniu sporą część czasu spędzisz na czytaniu kodu (często kogoś innego). Więc już teraz chciałabym Ci na to zwrócić uwagę, aby pisać czytelny kod. 😉

<?php
$variable = 'TEST';   
/* pierwsza linia komentarza
druga linia komentarza */ 
$variable = 123;
echo $variable;

Czy komentarze są dobre?

Komentarze są wymienione na liście brzydkich zapaszków (code smells) [więcej o code smells], jednakże autorzy książki „Refaktoryzacja. Ulepszanie struktury istniejącego kodu” stwierdzają, że same w sobie komentarze są przyjemne. Zwracają uwagę na komentarze, ponieważ są często stosowane jako dezodorant, który ma zamaskować problem. Więcej na ten temat znajdziesz w moim wpisie „Code Smell: Comments„. Jednakże na tym etapie – gdy uczysz się programować, komentarze mogą się okazać dla Ciebie pomocne. Stąd też w nadchodzących wpisach będę je wykorzystywać, aby tuż przy kodzie pisać swoje notatki dla Ciebie 😄. Jednakże, gdy zaczniesz myśleć o kierunku bardziej profesjonalnym, to zachęcam Cię do zapoznania się z moim wpisem w którym opisuję dlaczego komentarze są zazwyczaj traktowane jak brzydki zapaszek 🤢.

Dodatkowe materiały

Wydaje mi się, że powoli to czas na wprowadzanie dodatkowych materiałów dla Ciebie, tym bardziej, że w tym wpisie nie mam przewidzianych dla Ciebie ćwiczeń 😅

php.net

[www.php.net]

Jest to oficjalna strona PHP. Znajdziesz tam dokumentację wszystkich rzeczy dostępnych w PHP. Zauważyłam jednak, że wartościową częścią tej strony okazują się jej komentarze przy wpisach – gdzie użytkownicy dzielą się swoimi użyciami różnych funkcji (o tym co to jest funkcja jeszcze porozmawiamy 😉 ). Więc zachęcam do czytania również komentarzy tam 😉 Przez jakiś czas była tam również dokumentacja w języku polskim, ale niestety już nie widzę jej dostępnej, w związku z czym polecam Ci dokumentację w języku angielskim 😉 Jeśli chcesz poczytać więcej o komentarzach, możesz sięgnąć do źródła -> https://www.php.net/manual/en/language.basic-syntax.comments.php