09 / 01 / 2017 Developers

Jak komentować kod

Dzisiaj chciałbym opowiedzieć 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, dodatkowo 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 okomentowany?

Nie komentuj 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 kodu. 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, np taki fragment:

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

mógłby 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. Dzięki repozytorium kodu (jeżeli nasz program nie jest w repozytorium to jesteśmy w znacznie większych tarapatach niż przy źle zakomentowanym kodzie).

Kiedy jednak 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 takie komentarze – pamiętając, że komentarze 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 obiektywnego 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 to 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.

FacebookTwitterGoogle+LinkedIn