Komentując komentarze

Warto byłoby kiedyś stworzyć katalog zabobonów komputerowych. Moim zdaniem najczęściej pokutującym i stale powtarzanym przesądem z dziedziny inżynierii oprogramowania jest to, żeby w kodzie umieszczać wiele komentarzy. ''Linijka kodu, linijka komentarza'' - takie rady można usłyszeć od osób, które uważane są za doświadczonych informatyków.

Warto byłoby kiedyś stworzyć katalog zabobonów komputerowych. Moim zdaniem najczęściej pokutującym i stale powtarzanym przesądem z dziedziny inżynierii oprogramowania jest to, żeby w kodzie umieszczać wiele komentarzy. ''Linijka kodu, linijka komentarza'' - takie rady można usłyszeć od osób, które uważane są za doświadczonych informatyków.

Moje zdanie jest akurat odwrotne: uważam gęsto umieszczane komentarze za objaw jednej bądź kilku z następujących chorób: stosowania archaicznego języka programowania, marnego stylu programistycznego, nieuzasadnionej skłonności do optymalizacji albo niezorganizowanego procesu wytwórczego.

Zacznijmy od archaicznego języka programowania. Do zrozumienia instrukcji memcpy((*s)->ctempl, &(d.nn), sizeof(nier_t)) potrzebny jest niewątpliwie komentarz - i to pewnie nie linijka, a cały ekran - ale jeszcze bardziej potrzebne jest zastosowanie nowocześniejszego języka niż C. W podanej instrukcji (przykład z życia wzięty) chodziło o przekopiowanie informacji o nieruchomości z szablonu do nowo powołanej struktury. W porządnym, obiektowym języku (nawet w pokrewnym C++, ale także w Javie czy VB) taka instrukcja mogłaby wyglądać następująco: Wzorzec.PowołajKopię. I wtedy żaden komentarz nie byłby potrzebny.

Drugi problem, marny styl programistyczny, to na ogół wynik braku wykształcenia kierunkowego. Na przykład ludzie szukają złożonych i okrężnych mechanizmów tam, gdzie należałoby zastosować standardowy, np. używają tablicy tam, gdzie należałoby zastosować słownik. Zamiast opisowych nazw zmiennych i funkcji, stosuje się niezrozumiałe skróty; zamiast dbać o przejrzystość i oczywistość kodu, pisze się niezrozumiale, następnie "dokumentując" kod linijką komentarza.

Trzeci problem, nadmierna skłonność do optymalizacji, każe ludziom pisać programy tak, by były łatwe do zrozumienia dla komputera, a trudne dla człowieka. Muszą wtedy wyjaśniać, co mieli na myśli w komentarzu obok. Tymczasem kompilatory od dawna są w stanie optymalizować samodzielnie, a od lat istnieją narzędzia uruchamiania (profilery), które pomagają uderzyć prosto w newralgiczne punkty wydajności programu. Z reguły są to zupełnie inne miejsca niż te, których spodziewał się programista, pisząc kod. "Optymalny kod" zaś staje się koszmarem w przypadku śledzenia błędu lub przeróbki.

I wreszcie czwarty problem, niedojrzałość procesu. Ilekroć widzę komentarz w rodzaju: to jest procedura A, bierze parametry B, C i D, pisał ją osobnik E w dniu F, ciśnie mi się na usta pytanie - dlaczego te informacje znalazły się w kodzie? Czy powstała dokumentacja techniczna, w której znaczenie procedur i ich parametrów powinno być opisane? Czy jest opis koncepcji, myśli, która za danym kodem stoi? Czy stosowane jest narzędzie kontroli wersji, które śledzi kto i kiedy wykonał jakie zmiany? Jeżeli tak, to po co, u diabła, nadmiarowa informacja, która może się w pewnym momencie "rozjechać"? Jeżeli nie, to zamiast komentować, trzeba po prostu te elementarne narzędzia wdrożyć.

Aby być jednak uczciwym, dodam, że są sytuacje, w których komentowanie kodu jest potrzebne. Przede wszystkim wtedy, kiedy język czy szerzej - narzędzie - nie pozwala "powiedzieć tego, co pomyśli głowa". Tak, byśmy czytając program i towarzyszącą mu dokumentację, byli w stanie od razu wiedzieć, o co w tym wszystkim chodzi.

Nie chcę zniechęcać Państwa do stosowania komentarzy. Gorąco zachęcam po prostu do zatrudniania ludzi z porządnym przygotowaniem, pisania przy użyciu nowoczesnych narzędzi i w dobrym stylu, a nade wszystko do używania narzędzi procesowych w inżynierii oprogramowania.