Komentarze, czyli z pogranicza Code Smells

Komentarze

W każdym (przynajmniej tak mi się wydaje) języku programowania, jest możliwość wstawiania komentarzy do swojego kodu. Kiedyś, zwłaszcza w językach niższego poziomu, powszechnie stosowało się komentarz jako narzędzie do objaśniania konkretnej linii kodu. Dzisiaj często komentujemy w celach dokumentowania (tak jak dokumentacja XML w C#).

Codziennie można spotkać komentarz w gąszczu instrukcji warunkowych lub zagnieżdżonych pętli. Dziwne jest to, że potrafi on też jeszcze służyć za objaśnienie przeznaczenia zmiennej x – przecież dużo szybciej jest po prostu nadać zmiennej sensowną nazwę. We wspomnianych przeze mnie przypadkach, komentarz ‚śmierdzi’, bo pełni funkcję, której pełnić nie powinien – tłumaczy nam kod, który jest po prostu nie czytelny.

Rozróżniam dwa rodzaje komentarzy: Dobre – dokumentujące i Złe – tłumaczące. Komentarze dokumentujące są jednak dobre tylko wtedy gdy są sensowne (tzn. fajnie jeżeli jest to coś więcej niż nazwa klasy podzielona na wyrazy – patrz nieumiejętnie/leniwie wykorzystywany GhostDoc 😉 ). Generalnie wychodzę z założenia, że komentarz, jeżeli jest już użyty to nie powinien odpowiadać na pytanie JAK COŚ JEST ROBIONE? lub CO JEST ROBIONE? tylko: DLACZEGO COŚ JEST ROBIONE?

Głównym elementem dokumentacji na poziomie kodu źródłowego nie są komentarze, ale sam styl programowania. (…) W dobrze napisanym kodzie komentarze to tylko rodzynki w cieście czytelności. (McConnell 2004)

Prócz wspomnianych zastosowań komentarzy, powszechnie zauważa się jeszcze jeden: zakomentowany blok kodu, w celu jego wyłączenia, bo teraz nie jest potrzebny ale może kiedyś… . To kolejny przykład złego wykorzystania komentarzy.

Komentarze użyte we właściwy sposób robią dobrą robotę, natomiast, co ma miejsce w większości widzianego przeze mnie kodu, generują same problemy. Z których konieczność przeczytania komentarza – zamiast próby zrozumienia kodu, jest jedną z mniej poważnych. Widziałem też takie, które wprowadzały w błąd z racji braku aktualizacji komentarza po zmianach w kodzie – i to kolejna kwestia o której należy pamiętać: komentarzom nie należy bezgranicznie ufać. Jedynym, dającym pewność, sposobem zrozumienia kodu jest jego przeczytanie.

Myślę, że dobrym pomysłem są też komentarze określające szerszy kontekst. Np: Użyty wzorzec projektowy, link do pseudokodu algorytmu na wiki, lub do posta z dyskusją na forum. Jednak cały czas należy mieć na uwadze, że ktoś kto będzie modyfikował za jakiś czas nasz kod, może nie zaktualizować komentarzy przez co z powrotem mogą zacząć pełnić tylko szkodliwą funkcję 😉

 

 

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *