Ta kwestia od jakiegoś czasu zdaje się dzielić programistów niemalże tak mocno jak podział na zwolenników Javy i C# – czy trzeba komentować kod? Zwolennicy komentarzy twierdzą, że zwiększa to czytelność i stanowi rodzaj dokumentacji, przeciwnicy uważają, że kod powinien być zrozumiały bez dodatkowej pomocy. Która strona ma rację?
Każda linia się liczy
Warto zauważyć, że podejście nakazujące komentować każdą linijkę nie ma prawa bytu w wysokopoziomowych językach. Większość operacji nie wymaga tłumaczenia i o ile ktoś nie pisze w asemblerze, komentarze będą tylko zaciemniać kod.
A może każda funkcja?
Podobnie jest w przypadku reguł wymagających dokumentowania każdej funkcji, klasy czy metody w komentarzach – w większości jest to po prostu bez sensu. Jasne – fajnie jest mieć gotową dokumentację, ale takie podejście mija się z celem. W praktyce nikt nie będzie przekopywał się przez stos komentarzy po każdej drobnej zmianie w kodzie, przez co taka “dokumentacja” dość szybko staje się nieaktualna.
Nie wspominając już o przypadkach, w których pisze się na przykład gettery i settery do pól klasy i pomimo tego, że w zasadzie to nie powinno wymagać tłumaczenia, ktoś wymaga od nas komentarzy. To nie tylko marnowanie czasu i energii, ale ponownie, zaciemnianie kodu.
Nie bądźmy leniwi!
Czasami programiści używają komentarzy do zaznaczania sobie rzeczy do zrobienia albo, o zgrozo, do debugowania. W takich przypadkach komentowanie powinno być wręcz zakazane – do zaznaczania większych zadań powinno być osobne narzędzie (nawet, jeśli są to tylko samoprzylepne karteczki). Zapisywanie sobie rzeczy do zrobienia w kodzie to dość lekkomyślny ruch – najprawdopodobniej to przypomnienie odczyta ktoś inny. Za kilka miesięcy. Kiedy już nikt nie będzie miał pojęcia, o co dokładnie chodziło. No, chyba, że owe “todo” to zmiana jednej linijki, w takich przypadkach prościej będzie zrobić to od razu.
Jeśli chodzi o debugowanie przez komentowanie, to trudno w jakikolwiek sposób to usprawiedliwiać. Od tego przecież są systemy kontroli wersji, by móc bezkarnie usunąć fragment kodu i, gdy jednak okaże się potrzebny, wrócić do poprzedniego stanu. Ktoś mógłby to uznać za nieszkodliwe działanie – moim zdaniem zbyt często spotyka się wielkie, zakomentowane fragmenty kodu, które tylko zaśmiecają pliki i utrudniają rozumienie. Sprzątajmy po sobie!
Jasna strona mocy
Czy w takim razie komentarze są złe i powinniśmy z nich zupełnie zrezygnować? Nie wydaje mi się. Co prawda w większości przypadków kod da się napisać tak, by był całkowicie czytelny, ale czasem zdarzają się wyjątki. Być może użycie jakiejś magicznej stałej zwiększa wydajność – warto to zaznaczyć w kodzie, żeby nikt nigdy jej przypadkiem nie zmienił. Czasem problem może wymagać dość skomplikowanego algorytmu, który na pierwszy rzut oka nie wydaje się być do końca poprawny – warto w komentarzu dopisać, dlaczego tak naprawdę ma to działać. Wreszcie, czasem pomocne są komentarze, które wyjaśniają decyzje projektowe – nie zawsze oczywistym jest, dlaczego zostały podjęte takie, a nie inne decyzje. Komentarze mogą rozjaśnić nieco w głowie nowym osobom w projekcie. Albo nawet i autorom kodu, którzy będą musieli nad nim usiąść po jakimś czasie.
Wydaje mi się, że dobrym kryterium zasadności komentarzy jest: “Czy po tygodniu spędzonym nad zupełnie innym kodem będę w stanie bez problemu zrozumieć, co się tu dzieje?”. Jeśli odpowiedź brzmi “nie”, dodatkowy komentarz wydaje się być dobrym pomysłem.
Jaki wy macie stosunek do komentowania kodu? Może znacie jakieś przykłady “z życia”, w których komentarze były bez sensu? A może wręcz przeciwnie, jakiś komentarz pomógł wam w pracy? Podzielcie się swoją opinią poniżej.
[su_button url=”https://roboblog.eu/2016/05/13/pisac-dobry-kod/” desc=”Jak pisać dobry kod”]Poprzednia część[/su_button]