05-10-2022
Komentarze są wymienione na liście brzydkich zapaszków (code smells) [więcej o code smells], jednakże autorzy książki „Refaktoryzacja. Ulepszanie struktury istniejącego kodu” stwierdzają, że same w sobie komentarze są przyjemne. Zwracają uwagę na komentarze, ponieważ są często stosowane jako dezodorant, który ma zamaskować problem.
Komentarz sam w sobie nie jest przykrym zapaszkiem w naszej analogii, wręcz przeciwnie, pachnie bardzo przyjemnie. Zwracamy uwagę na komentarze dlatego, że nierzadko są one używane jako dezodorant, który ma zamaskować problem. Bardzo często stwierdzamy, patrząc na obficie komentowany kod, że komentarze wprowadzono do niego dlatego, że sam kod jest bardzo zły.
Martin Fowler, Kent Beck
Skomplikowany kod
Zazwyczaj jak już jest komentarz w kodzie to sprowadza się do tego, że opisuje on w miarę sensownie co się dzieje dalej. Komentarz w tym miejscu wydaje się bardzo przydatny bo kod poniżej wygląda zazwyczaj jak masło maślane i nie jest to najprzyjemniejszy kod do czytania. Ale czy w związku z tym nie powinno się tego kodu przepisać, aby był bardziej czytelny? W mojej opinii powinno. Jeśli mamy taką część kodu, którą trzeba skomentować możesz rozważyć wyniesienie jej do metody i nazwanie odpowiednio metody, tak, aby mówiła co się tam dzieje. Dzieje się za dużo? Może należy rozbić to na kilka metod/klas?
Co zyskujemy modyfikując kod i usuwając komentarz?
- Jedną z rzeczy jaką zauważyłam w pracy, jest to, że podczas modyfikacji kodu, komentarz nie jest aktualizowany. Potem w projekcie, który ma X lat widzę komentarze w kodzie, które kompletnie nie mają sensu. Ich pozostawienie jednak wywołuje poczucie niepewności, bo nie jestem pewna czy ten komentarz zapomniano usunąć, czy może jednak on ma jakieś głębsze przesłanie i powinien pozostać, bo jest coś czego nie widzę?
- Po drugie, jeżeli logika jest tak skomplikowana, że potrzebuje komentarza, to aż samo się trochę prosi o refaktoryzację 😉 (refaktoryzacja to modyfikacja kodu do bardziej czytelnej/odpowiedniejszej postaci przy jednoczesnym nie zmienianiu funkcjonalności). Po refaktoryzacji kod powinien być bardziej czytelny, co prowadzi do zmniejszenia możliwego popełnienia błędu w danym fragmencie kodu.
Tajemnicze liczby, treści
Innym przypadkiem w którym spotykam się z komentarzami w kodzie są miejsca gdzie używana jest jakaś tajemnicza liczba lub tekst. Przykładowo:
// 2 - status active
if ($status === 2) {
// ...
}
W tej sytuacji mamy tajemniczą liczbę 2…
W mojej opinii lepszy podejściem byłoby porównywanie do stałej.
if ($status === Status::ACTIVE) {
// ...
}
Co zyskujemy modyfikując kod i usuwając komentarz?
- Mamy stałą, którą możemy wykorzystywać w całym systemie. W związku z czym nie będzie trzeba pamiętać, że 2 to oznacza active, tylko będzie to wynikało wprost ze stałej.
- Przy dużej ilości statusów idzie bardzo łatwo pomylić liczby (been there done that… 😅 🙈), więc stałe są lepszym rozwiązaniem.
Kiedy warto dać komentarz?
Zauważyłam 2 przypadki w których taki komentarz w moim odczuciu bym pozostawiła.
- Wyobraź sobie sytuację, gdy integrujesz się z jakimś API. Powiedzmy, że odkrywasz, że pomiędzy 2 konkretnymi requestami musisz odczekać 5 sekund, bo w przeciwnym wypadku cały proces przestaje działać. Zgłaszasz tej firmie wystawiającej API problem. Ale co teraz? Dopóki nie naprawią błędu masz w kodzie tajemniczego sleep’a na 5 sekund. W takiej sytuacji jakiś dłuższy komentarz z informacją, że czekamy na poprawkę od firmy i dlatego daliśmy tego sleep’a wydaje się całkiem sensowny jak dla mnie. Nazwa metody mogłaby nie oddać sensu tego sleepa, oraz tego, że czekamy na poprawkę i że kiedyś będzie można to usunąć.
- W projektach Legacy (kod który jest trudny w utrzymaniu i rozwijaniu) wprowadzanie zmian odbywa się etapami. W takich projektach zmiana całej funkcjonalności, bądź wprowadzenie nowej potrafi trwać 2-3 lata. W takich sytuacjach czasami się przydaje komentarz typu „przy realizacji taska XYZ / przy usuwaniu feature ZYX usunąć/zmienić ten fragment kodu”. Widziałam już „kilka” sytuacji, gdzie taki komentarz uratowałby skórę programistów przed gromem zdenerwowania klientów. Ktoś mógłby zauważyć, ale jak to przeszło testy?!?!?! No cóż… w projektach legacy czasami ciężko jest stwierdzić na co zmiana może wpłynąć, a potem jest już za późno 😐
Podsumowanie
W mojej opinii, jeśli będziesz mieć ochotę napisać komentarz w kodzie, zastanów się czy nie da się tego kodu napisać inaczej. Czy ten kod nie mógłby być bardziej sam z siebie czytelny? Są też sytuacje, kiedy komentarz może się okazać przydatny, które wymieniłam w poprzedniej sekcji. A co Ty myślisz o komentarzach w kodzie? Znasz jeszcze jakieś miejsca w których komentarz okazuje się pomocy, a refaktor kodu by nie rozwiązał tego problemu? 🤔
Źródła
- książka: Refaktoryzacja. Ulepszanie struktury istniejącego kodu, Martin Fowler we współpracy z Kentem Beckiem
- www: Bad Smells in Software – a Taxonomy and an Empirical Study, Mika Mäntylä
- www: Code Smells, Jeff Atwood