Komentować kod czy nie? Programistyczne dylematy

Wstawiać komentarze w kodzie programu czy też nie wstawiać? To jeden z wielu dylematów programisty, przed którymi staję na co dzień piszący kod, niezależnie od wybranego języka programowania - czy to będzie C++, .NET, Java czy Python. Może nieraz stałeś przed dylematem - czy komentować własny kod. To jeden z wielu wyborów, w stylu pisania czy też w podejściu do pracy. I jak to zwykle bywa zdania są podzielone, również na temat komentarzy do kodu.

Jakie mogą być powody, dla których pisanie komentarzy - do własnego kodu - posiada zalety przeważające nad wadami? Co pierwsze przychodzi do głowy, z własnych doświadczeń z PHP: czy zdarzyło ci się, wróciwszy do programu pisanego przed kilku laty, że musiałeś mocno sobie przypominać, co wykonuje dany fragment, czy dana metoda w danej klasie na takie czy inne zastosowania? A co dopiero, gdy o trzeciej nad ranem jest bug i trzeba znaleźć przyczynę wysypania się programu?

Mówi się, że dobrze napisany kod musi posiadać dobre nazewnictwo. Dotyczy to nazw zmiennych, funkcji (metod) czy klas. Wiele osób wśród deweloperów – dawniej zwanych programistami - uważa, iż dobrze napisany kod nie wymaga komentowania. Czy aby na pewno?

Zabawmy się w sondę uliczną na temat komentowania kodu, „pytając” wśród programistów. A może napiszę nieistniejący wywiad. Zacznijmy od strony na „nie”  czyli od wszystkich programistów piszących „nie komentuj”.

Jakie są argumenty za tym, aby nie pisać komentarzy?

Najczęściej przytaczany argument przeciwników komentarzy to: „dobrze napisany kod jest samo komentujący się i nie wymaga żadnych dodatkowych podpowiedzi autora dla osób, które w późniejszym czasie będą pracować nad całością lub jego częściami”.

Mówi się przy tym że zamiast komentować lepiej refaktoryzować kod. Cytując Briana Keringhana : Don't comment bad code, rewrite it.

Drugi podawany przez wielu przeciwników komentowania argument, to niebezpieczeństwo rozsynchronizowania się kodu z komentarzami, gdy program był zmieniony natomiast komentarze zostały.

Gdyż aktualność komentarzy jest realna tylko w momencie pisania programu.

Przeciwnicy komentowania podają jednak kilka wyjątkowych sytuacji, w których komentarze mogą być niezbędne. Choćby taka, gdy piszemy wyrażenie regularne (jest to zrozumiałe ze względu na enigmatyczną składnię regexp). Podobnie wyglądają operacje bitowe, czy assembler. Tu się nie da zrozumieć kodu - po jego napisaniu - bez komentarzy.

Druga grupa przykładów, to zadania do wykonania typu TO-DO , objaśnienie intencji, standardów, pewnych niuansów czy wytycznych biznesowych.  Puryści kodowania zaprzeczają takiej potrzebie, mówiąc, że wszelkie „to-do” czy niuanse bądź kwestii biznesowe należy opisać w dokumentacji, nie duplikując jej. Ma to pewien sens, gdyż dokumentacja programu podlega kontroli wersji, a komentarze mogą zostać niezmienione w kodzie na amen.

Zadania do wykonania - chyba też nie są poszukiwane przez osoby decyzyjne w komentarzach do programu.

A co na to zwolennicy pisania komentarzy do kodu?

„Korzystając ze swojego edytora wyrabiaj sobie nawyki.(…) Jednym z takich nawyków jest używanie komentarzy (…) Metoda ta zadziała w każdym języku. Pamiętaj więc - jeżeli chcesz gdziekolwiek wstawić komentarz - czy to w CSS, HTML, Javascript czy podobnych - Ctrl + / są twoim przyjacielem”. Kurs html – tylko czy to jest programowanie? – głosi o komentarzach:  „Początkujący developerzy raczej rzadko ich używają, ale ja gorąco zachęcam do komentowania własnego kodu. Gwarantuję, że usprawni to i uprzyjemni waszą pracę”. Takie porady raczej nie uratują naszych nieprzespanych nocy… To co mamy w kodzie html, css, nie do końca przekłada się na prawdziwe języki programowania. Klasy? Interefejsy? Singletony? Dziedziczenie?

A co na temat komentowania podaje angielskojęzyczny internet? Za czy przeciw? Zwolennicy utrzymują, że:

- komentarze czyta się szybciej i łatwiej od programu, zaś
- z komentarzy można szybko utworzyć dokument html (dokumentacja).

- dodatkowo, podnosi się argument, iż pisanie samo-komentujących się nazw (i potem ich stosowanie) też zabiera czas i miejsce, weźmy metodę (dobrze nazwaną, zgodnie z tym do wykonuje):

function czyUzytkownikMaMiecMultisportCoMiesiąc(idKadrowyUzytkownika, idDzialuKorporacji)

Użyj takiej metody 10 razy w jednym pliku 😊 (Mnie taka konwencja nazw w kodzie dobija).

- doświadczeni programiści wskazują też na korzyści komentowania i egoistyczne podejście niektórych koderów pod hasłem „mój kod jest czytelny i samo-komentujący się”. A życie weryfikuje takie postawy. Czyli z trzech stanowisk - nie pisać, pisać komentarze, komentować wszystko ile się da – trudno wybrać złoty środek. Kolejne podejście – czysto praktyczne – mówi, że wszystko zależy od kontekstu.  

Rada z redditu

Jeszcze na koniec, rada znaleziona na reddicie, nie podam teraz kogo, że komentarze nie mają odpowiadać na pytanie „how” (jak to jest zrobione?) tylko „why” (dlaczego to tak zaprogramowałem?), co może pomóc w szukaniu błędów czy w udoskonalaniu funkcjonalności.