Mało pomocne komentarze łatwiej napisać niż dobre, a komentowanie może
przynieść więcej szkody niż korzyści. Gorące dyskusje, w których podkreśla
się najróżniejsze zalety szczegółowych komentarzy, przypominają często filo-
zoficzne debaty nad wartościami moralnymi. Myślę, że gdyby Sokrates był
programistą, mógłby przeprowadzić ze swoimi uczniami następującą dyskusję.
Komento, czyli pamiętaj o komentarzach
Osoby:
THRASYMACHUS — początkujący purysta teoretyk, który wierzy we wszystko,
co czyta.
KALIKLES — zaprawiony w walkach weteran starej szkoły, czyli „prawdziwy
programista”.
GLAUKON — pewny siebie, ambitny młodzik.
ISMENA — starsza programistka znużona wielkimi obietnicami i nadzieja-
mi, szukająca prostego zbioru zasad, które sprawdzą się w praktyce.
SOKRATES — stary, mądry programista.
Miejsce i czas:
KOŃCÓWKA CODZIENNEGO SPOTKANIA ZESPOŁU
— Czy ktoś ma jeszcze jakieś tematy, zanim wrócimy do pracy? — spytał
Sokrates.
— Chciałbym zaproponować konwencję pisania komentarzy w naszych pro-
jektach — powiedział Thrasymachus. — Niektórzy z programistów prawie
nie komentują kodu, a wszyscy wiemy, że kod bez komentarzy jest nieczytelny.

— Widzę, że nauki szkolne są Ci jeszcze bliższe, niż myślałem — odpowiedział
Kalikles. — Komentarze to akademickie lekarstwo na wszystko, ale każdy, kto
miał do czynienia z programowaniem w praktyce, przekonał się, że komentarze
bardziej utrudniają czytanie kodu, niż ułatwiają. Język naturalny jest mniej
precyzyjny niż Java czy Visual Basic, wymaga też dużo więcej słów. Instrukcje
języka programowania są krótkie i dokładne. Jeżeli nie jesteś w stanie zbudować
przejrzystego kodu, jak wprowadzisz przejrzyste komentarze? Dodatkowo
komentarze z czasem się dezaktualizują. Uwierzysz w taki nieaktualny komen-
tarz i już po Tobie.
— Też tak uważam — dodał Glaukon. — Kod z dużą liczbą komentarzy trud-
niej czytać po prostu dlatego, że jest go więcej. Wystarczy, że muszę przeczytać
program. Po co jeszcze męczyć się z komentarzami?
— Moment — powiedziała Ismena, odstawiając kubek, aby dorzucić swoje
dwie drachmy. — Wiem, że komentarzy może być za dużo i mogą być złe, ale
dobre komentarze są na wagę złota. Pracowałam z kodem z komentarzami
i z kodem bez komentarzy i zdecydowanie wolę pracować z kodem dobrze
opisanym. Nie sądzę, żeby było celowe wprowadzanie konwencji, która mówi,
że należy wprowadzać jeden komentarz na x wierszy kodu, ale lepiej zachęcać
do komentowania niż twierdzić, że komentarze nie są potrzebne.
— Jeżeli komentarze są stratą czasu, Kaliklesie, to po co w ogóle ludzie ich
używają? — spytał Sokrates.
— Albo dlatego, że są do tego zmuszani, albo dlatego, że przeczytali, że jest to
korzystne. Nikt, kto zastanowił się nad tą kwestią, nie powie, że komentarze
są naprawdę ułatwieniem.
— Ismena tak uważa. Jest z nami od trzech lat, pracuje z Twoim kodem bez
komentarzy i innym kodem z komentarzami, a woli ten drugi. Co Ty na to?
— Komentarze nie mają sensu, bo są po prostu powtórzeniem kodu w bardziej
rozwlekłym...

— Zaczekaj — przerwał Thrasymachus. — Dobre komentarze nie powtarzają
i nie objaśniają kodu. Informują o jego celu. Komentarze powinny wyjaśniać
na wyższym poziomie abstrakcji niż kod, co próbujesz zrobić.
— Właśnie — powiedziała Ismena. — Przeglądam komentarze, gdy szukam
części kodu odpowiedzialnej za to, co mam zmienić lub poprawić. Masz rację,
że komentarze, które są powtórzeniem kodu, nie są żadną pomocą, bo wszyst-
kie informacje są już w samym kodzie. Gdy czytam komentarze, oczekuję, że
będą jak nagłówki lub spis treści w książce. Ułatwia mi to znalezienie właści-
wego miejsca w programie. Dopiero po jego znalezieniu rozpoczynam czyta-
nie kodu. Dużo szybciej można przeczytać jedno zdanie w języku naturalnym
niż przeanalizować 20 wierszy kodu języka programowania — Ismena nalała
sobie kolejny kubek kawy.
— Myślę, że osoby, które nie chcą pisać komentarzy, (1) uważają, że ich kod
jest bardziej przejrzysty, niż to w ogóle możliwe, (2) uważają, że inni progra-

miści są bardziej zainteresowani ich kodem niż w rzeczywistości, (3) uważają,
że inni programiści są inteligentniejsi niż w rzeczywistości, (4) są leniwi i (5)
boją się, że ktoś mógłby się zorientować, jak działa ich kod.
— Przeglądy kodu byłyby w tej kwestii dużą pomocą, Sokratesie — kontynu-
owała Ismena. — Gdy ktoś, kto twierdzi, że nie musi pisać komentarzy, zosta-
nie zasypany pytaniami w trakcie przeglądu — gdy wszyscy ciągle będą pytać:
„Co właściwie próbujesz tutaj zrobić?” — to szybko nauczy się dobrze komen-
tować kod. Jeżeli nie dojdzie do tego sam, szef zespołu i inni będą przynajm-
niej mieli argumenty.
— Nie twierdzę, że jesteś leniwy czy boisz się tego, że inni zrozumieją Twój
kod, Kaliklesie. Pracowałam z Twoim kodem i wiem, że jesteś jednym z najlep-
szych programistów w firmie. Ale miej litość, co? Dużo łatwiej pracowałoby
mi się z Twoim kodem, gdybyś wprowadzał komentarze.
— Ale to marnowanie zasobów — zaprotestował Kalikles. — Dobry kod powi-
nien opisywać się sam. Powinien zawierać wszystko, co potrzebne do jego zro-
zumienia.
— W żadnym razie! — Thrasymachus już zerwał się z krzesła. — W kodzie
jest wszystko, czego potrzebuje kompilator! Równie dobrze można powie-
dzieć, że wszystko, czego potrzebujesz, jest w binarnym pliku wykonywalnym!
Gdybyś tylko był w stanie objąć to umysłem! Tego, co powinno się zdarzyć,
nie ma w kodzie.
Thrasymachus zdał sobie sprawę z tego, że stoi, i usiadł.

— Sokratesie, to jest niepoważne. Dlaczego rozmawiamy o tym, czy wprowadza-
nie komentarzy jest korzystne? Cokolwiek czytałem, wszyscy piszą, że komenta-
rze są ważne, choć można opisywać kod na różne sposoby. Wydaje mi się, że
tracimy czas.

— Spokojnie, Thrasymachusie. Spytaj Kaliklesa o jego doświadczenie w pro-
gramowaniu.
— Ile to już lat, Kaliklesie?
— Zacząłem od Acropolis IV 15 lat temu. Myślę, że miałem okazję obserwować
już kilkanaście systemów od momentu powstania aż po ich koniec. W dwukrot-
nie większej liczbie projektów pracowałem nad istotnymi częściami oprogra-
mowania. Dwa z tych systemów miały ponad pół miliona wierszy kodu, więc
wiem, o czym mówię. Komentarze praktycznie nic nie wnoszą.
Sokrates spojrzał na młodego programistę.
— Jak mówi Kalikles, z komentarzami wiąże się wiele istotnych problemów
i trudno zdać sobie z nich wszystkich sprawę bez odpowiedniego doświadcze-
nia. Złe komentarze są nie tylko bezużyteczne, ale i szkodliwe.
— Nawet poprawne komentarze są bezużyteczne — powiedział Kalikles. —
Komentarze są mniej dokładne niż język programowania. Wolę już, żeby ich
w ogóle nie było

— Zaczekaj chwilę — powiedział Sokrates. — Ismena zgadza się z tym, że
komentarze są mniej precyzyjne. Zwraca jednak uwagę na to, że zapewniają
one wyższy poziom abstrakcji, a wszyscy wiemy, że poziomy abstrakcji to
jedno z najpotężniejszych narzędzi programisty.
— Nie zgadzam się z tym — odpowiedział Glaukon. — Zamiast koncentro-
wać się na komentarzach, lepiej włożyć więcej wysiłku w czytelność samego
kodu. Refaktoryzacje prowadzą do wyeliminowania większości moich komenta-
rzy. Po odpowiednich przekształceniach w kodzie może pojawić się 20 czy 30
wywołań procedur, które nie potrzebują żadnego dodatkowego opisu. Dobry
programista odczyta zamierzenia autora z samego kodu, a co wnosi czytanie
o czyichś intencjach, o tym, jak kod powinien działać, jeżeli kod ten zawiera
błędy? — Glaukon był wyraźnie zadowolony ze swoich spostrzeżeń. Kalikles
potakiwał ze zrozumieniem.
— To, co mówicie, sprawia wrażenie, jakbyście nie mieli nigdy do czynienia
z cudzym kodem — powiedziała Ismena. Kalikles nagle zainteresował się śladami
ołówka na kasetonach pokrywających sufit.
— Może spróbujecie kiedyś przeczytać swój własny kod pół roku czy rok po
jego napisaniu? Byłaby to okazja do poprawienia umiejętności czytania kodu
i dobrego komentowania. To nie jest kwestia wyboru typu „albo jedno, albo
drugie”. Przy czytaniu powieści nagłówki rozdziałów mogą nie być potrzeb-
ne. Jednak gdy czytasz książkę techniczną, musisz mieć możliwość szybkiego
wyszukiwania potrzebnych informacji. Nie można zmuszać czytelnika do prze-
glądania w pełnym skupieniu setek wierszy kodu w poszukiwaniu dwóch banal-
nych wierszy do zmiany.
— OK, rozumiem, że możliwość przeglądania kodu mogłaby być pomocna —
powiedział Glaukon. Widział już kilka programów Ismeny i zrobiły one na nim
duże wrażenie. — Ale co z drugim argumentem Kaliklesa, że w toku wpro-
wadzania zmian komentarze ulegają dezaktualizacji? Pracuję jako programista
dopiero od kilku lat, ale miałem już okazję przekonać się, że nikt nie dba o aktu-
alizowanie komentarzy.

— I tak, i nie — powiedziała Ismena. — Jeżeli traktujesz komentarz jak świę-
tość, a kod jak coś, czemu nie można ufać, prosisz się o kłopoty. W istocie
znalezienie rozbieżności między komentarzem a kodem oznacza zazwyczaj,
że i kod, i komentarz zawierają błędy. Sam fakt, że nie wszystkie komentarze są
dobre i pomocne, nie oznacza jeszcze, że sama zasada komentowania kodu
jest zła. Idę wstawić wodę na nową kawę. — Ismena wyszła z pokoju.
— Moim głównym zarzutem dotyczącym komentarzy — powiedział Kalikles —
jest to, że zajmowanie się nimi jest marnowaniem zasobów.
— Czy ktoś może wskazać metody, które pozwalają zmniejszyć czas zajmowany
przez pisanie komentarzy? — spytał Sokrates.
— Projektowanie procedur w pseudokodzie i konwertowanie pseudokodu na
komentarze przy wpisywaniu właściwego kodu — powiedział Glaukon.

— OK, to mogłoby mieć sens, o ile komentarze nie powtarzałyby kodu —
powiedział Kalikles.
— Pisanie komentarzy zmusza do głębszego przemyślenia tego, co dokładnie
robi kod — powiedziała Ismena, która wróciła już z pokoju socjalnego. — Jeżeli
napisanie komentarza sprawia trudności, oznacza to, że kod jest źle skonstru-
owany lub sam programista słabo rozumie jego działanie. W każdym z tych
przypadków trzeba poświęcić więcej czasu na pracę z kodem. W efekcie czas
poświęcony komentarzom nie jest stracony, bo prowadzi do identyfikacji miejsc
w programie, które wymagają dodatkowej pracy.
— W porządku — powiedział Sokrates. — Nie przychodzi mi do głowy więcej
pytań, ale myślę, że Ismena dała Wam dzisiaj w kość. Starajmy się komento-
wać kod, ale nie róbmy tego bezmyślnie. Będziemy organizować przeglądy
kodu, aby każdy mógł się zorientować, jakie rodzaje komentarzy są faktycznie
pomocne. Jeżeli pojawiają się problemy ze zrozumieniem cudzego kodu, nie
warto zwlekać z informowaniem autora o możliwościach jego poprawienia.