Jak komentować kod?

Dzisiaj chciałbym powiedzieć kilka słów o podejściu do komentowania kodu. Wielu początkujących programistów będzie zapewne pod wrażeniem, widząc kod zawierający komentarz na końcu każdej linijki, komentarze blokowe przed wybranymi fragmentami programu i oczywiście docblocki do plików, klas i metod w kodzie. Przyjrzyjmy się jednak temu zagadnieniu bliżej – czy na pewno kod powinien być tak mocno komentowany?

Najważniejsze – nie „komentuj” własnego kodu

Dobrze napisany kod jest samokomentujący się i nie wymaga żadnych dodatkowych podpowiedzi autora dla osób, które w późniejszym czasie będą pracować nad danymi fragmentami. Używanie intuicyjnych (nawet dłuższych) nazw zmiennych, metod i klas, krótkie metody i praca na jednym poziomie abstrakcji w obrębie jednej klasy pozwala na swobodne zrozumienie fragmentów programu bez komentarzy. Lepiej jest wyrażać swoje intencje w kodzie poprzez jego odpowiednie pisanie niż opatrywanie go komentarzem. Weźmy pod lupę taki fragment:

//pracownik może posiadać multisport
$employee->isActive() && $emplyee->getMonths() > 3

Mógłby on być z powodzeniem zastąpiony przez wydzielenie tej logiki do osobnej metody:

$employee->isMultisportApplicable()

Pomocna podczas pisania programów może być ta sentencja:

„Don’t comment bad code – rewrite it.” (Brian W. Kerninghan and P. J. Plaugher)

Dlaczego nie „komentujemy” kodu

Powstaje oczywiście pytanie, dlaczego nie dodawać komentarzy do napisanych fragmentów kodu. Otóż komentarze są częścią kodu i wymagają takiej samej opieki jak kod. Kod z komentarzami jest chociażby dłuższy dlatego jego refaktoryzacja/przebudowa/rozwój jest trudniejszy. Przy refaktoryzacji kodu należy także zadbać o przeniesienie lub zmianę komentarzy odpowiadających refaktorowanym fragmentom programu. Przy rozwoju należy zwracać uwagę czy wstawiane nowe fragmenty kodu nie powodują np. że komentarze są w miejscu, które nie jest najbliżej fragmentu kodu, którego dotyczą. Źle umieszczony kod może być bezużyteczny dlatego lepszym rozwiązaniem jest samokomentujący się kod, który na pewno posiada odpowiednie wyjaśnienia w miejscu, w którym są potrzebne. Również nie powinniśmy komentować kodu “na przyszłość”. Taki zakomentowany fragment kodu będzie rodził dodatkowe pytania przy refaktoryzacji, debugowaniu lub rozwoju kodu.

Kiedy komentujemy kod

Oczywiście są sytuacje, które wymagają użycia komentarza.

1. Mogą występować standardy w projekcie, które wymagają stosowania komentarzy do plików/klas/metod – nie dyskutujemy z takimi wymogami i po prostu stosujemy komentarze, pamiętając, że one również wymagają uwagi podczas zmian w kodzie;
2. Wyjaśnienie kodu, który nie jest oczywisty na pierwszy rzut oka. Przykładowo do jakiego wzorca dopasowuje dany regexp;
3. Wyjaśnienie intencji, które ciężko ująć w kodzie. Przykładowo dlaczego uznajemy pierwszy obiekt za większy od drugiego przy implementacji metody compareTo;
4. Ostrzeżenie o konsekwencjach użycia danej funkcjonalności. Przykładowo w testach, które mogą czyścić bazę danych lub trwać dłuższy czas;
5. Wyjaśnienie niuansów procesów biznesowych, które realizuje program;
6. Komentarze TODO – w przypadku gdy w danej chwili nie jest możliwe wdrożenie pełni funkcjonalności z jakiegokolwiek powodu;

Przy komentowaniu kodu powinniśmy zdecydowanie zwracać uwagę na miejsce umieszczania komentarzy – im bliżej fragmentu kodu którego dotyczy komentarz tym lepiej. Podczas rozwoju kodu powinniśmy zwracać uwagę czy komentarze po zmianach w kodzie nie wymagają refaktoryzacji.

Podsumowanie

Jeżeli Twój kod nie wymaga komentarzy, prawdopodobnie jest to wynikiem dobrze wykonanej pracy i dobrej jakości kodu. Jeżeli uważasz, że wybrany fragment wymaga opatrzenia go komentarzem, to jest to pierwszy sygnał do zastanowienia się nad refaktoryzacją kodu – nie należy go ignorować, a skorzystać z szansy na refaktoryzację i polepszenie swoich umiejętności programistycznych.