Komentarze w kodzie

Jak wiadomo (choć życie pokazuje, że nie wszystkim) komentarze w kodzie zdecydowanie nie należą do dobrych praktyk. Wiele osób twierdzi, że jeżeli kod wymaga komentarza, to jest po prostu źle napisany. I zazwyczaj tak właśnie jest. Są jednak wyjątki, o których za chwilę. Na początek jednak trochę o tym jak radzić sobie z dość często spotykanymi typami komentarzy, które wydają się być niezbędne, przynajmniej w odczuciu ich autorów 😉 .

Komentowanie liczb

Niepodważalnie magic numbers to „zuo”. Dlatego niektórzy postanawiają obłożyć je komentarzem, aby wiadomo było skąd wzięła się dana liczba.

Nie przeczę, lepszy komentarz niż goła liczba, ale jednak nie jest to idealne rozwiązanie. Dużo lepszą opcją jest utworzenie stałej w klasie, albo przynajmniej zmiennej lokalnej, która po prostu będzie opisywać czym dana liczba jest. Nawet jeżeli zmienna/stała będzie użyta tylko w jednym miejscu to i tak warto ją utworzyć właśnie ze względu na czytelność kodu.

Komentowanie if’ów

Innym stosunkowo częstym przypadkiem, z którym się spotykam jest komentowanie złożonych warunków w instrukcji if. Tego typu komentarze też bywają pomocne w zrozumieniu kodu, jednak dużo czytelniejszym rozwiązaniem jest po prostu wydzielenie poszczególnych warunków do odpowiednio nazwanych metod prywatnych. Dzięki temu pozbywamy się potworka, który odstrasza samym widokiem i zyskujemy czytelny opis tego co sprawdzamy.

Poniżej jest metoda, która zmienia zaznaczenie elementu w jakimś zbiorze, o ile spełnione są pewne warunki w instrukcji if (przykład może trochę naciągany, ale mam nadzieje, że idea będzie zrozumiała).

Kiedy mamy do czynienia z tak rozległymi warunkami w if’ie pierwsze co warto zrobić to wydzielić wszystkie te warunki do osobnej metody. Następnie poszczególne fragmenty zostały wydzielone do małych metod, które swoimi nazwami zastępują komentarze. W efekcie prezentuje się to znacznie czytelniej. Jeżeli ktoś będzie chciał to wejdzie do poszczególnych metod, aby sprawdzić jakie dokładnie sprawdzane są warunki, ale w większości przypadków ogólna inforacja jaką daje nazwa metody będzie w pełni wystarczająca.

TODO

Chyba najczystszym komentarzem jaki spotykamy w kodzie jest TODO. Zazwyczaj wisi on w kodzie miesiącami, latami i nic z niego nie wynika. Nie wiadomo kto ma coś zrobić, a często nawet co trzeba zrobić. Jego jedyną funkcją jest zaciemnianie kodu.  Żeby umieszczanie tego typu komentarzy miało jakiś sens trzeba utworzyć konkretnego taska w systemie kontroli wersji i dodać jego numer do komentarza. Wtedy jest szansa, że temat nie umrze, bo będzie gdzieś w taskach oczekujących na realizację i jak ktoś po dłuższym czasie będzie się zabierał za realizację tego zadania to łatwiej będzie mu zlokalizować miejsce w kodzie, gdzie powinien zrobić zmiany. Jeżeli jednak dodacie sam komentarz to prawdopodobnie będzie on sobie tak wisiał przez wieki i nikt się tematem nie zainteresuje.

Zostawię to na później

Niewątpliwie popularne jest też zostawianie zakomentowanego kodu na później.  No bo przecież skoro już coś napisałem to szkoda usuwać może się kiedyś jeszcze przydać. Ja osobiście jak widzę coś takiego to od razu to usuwam, bo tylko zaciemnia to właściwy kod, a jak ktoś będzie rzeczywiście potrzebował ponownie tego kodu (co sie raczej rzadko zdarza) może go wygrzebać z repozytorium kodu.

Dopuszczalne komentarze w kodzie

Moim zdaniem jest jeden typ komentarzy objaśniających kod, który jest dopuszczalny i niesie ze sobą jakąś wartość dodaną, której nie ma jak ująć w samym kodzie. Są to komentarze, które nie mówią jak coś zostało zrobione, tylko dlaczego tak zostało zrobione. Oczywiście nie mam tu na myśli przepisywania specyfikacji biznesowych do komentarzy w kodzie. Chodzi np. o jakieś hacki i obejścia, które wyglądają nieco dziwnie, albo na pierwszy rzut oka wydają się być zbędnym fragmentem kodu, który prosi się o usunięcie. W takich sytuacjach warto wyjaśnić w komentarzu dlaczego zostało to zrobione właśnie w ten sposób.

Jakie jest Wasze zadnie na temat komentowania kodu i jak to wygląda w Waszych projektach? 😉

 

Dodaj komentarz

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