Czysty kod - komentarze

Przedstawię tutaj moją opinie (opartą na doświadczeniu, książkach oraz opiniach innych ludzi) na temat komentarzy w kodzie.

Co to są komentarze?

Wiem, każdy wie co to są komentarze. Przedstawię tutaj tylko inną definicje komentarzy. Komentarze to ZŁO (czasami konieczne). Zaraz dowiecie się dlaczego.

Komentarze opisujące kod

Jestem całkowitym przeciwnikiem komentarzy, ale często sam je stosuje. Zapytać teraz możecie "ej, ale dlaczego?". Wykorzystuje je właśnie jako pomocnik do poprawy czytelności cudzego, a nawet czasami swojego, kodu. Staram się nie zostawiać komentarzy w kodzie. Są one półśrodkiem do refaktoringu. Refaktoring dużej, brzydkiej i nieczytelnej funkcji zaczynam właśnie od podzielenia kodu tej funkcji na sekcje i napisaniu odpowiedniego komentarza opisującego te bloki kodu. I tutaj właśnie zauważyć można dlaczego tak surowo oceniłem komentarze. Uważam, że komentarze po prostu próbują zaślepić użytkownika kodu, aby nie zauważył, że jest napisany źle i nieczytelnie. Kod sam z siebie nie wyjaśnia co robi i dlatego potrzebny jest komentarz.

Wyjaśniłem przed chwilą komentarze, które opisują fragmenty kodu. Są jeszcze komentarze innych typów.

Komentarze TODO, FIXME itp.

Tego typu komentarze sugerują, że system nie działa prawidłowo. Skoro trzeba coś napisać lub poprawić to znaczy, że czegoś brakuje lub coś źle działa. Powinniśmy tego typu komentarze eliminować na bieżąco. Istnieją projekty, które posiadają tysiące znaczników TODO i wiecie co? W tych projektach rzadko znajduje się osoba, która spojrzałaby na tego typu komentarze. Rozumie, że komentarze tego typu są potrzebne i wiem o tym, ale powinniśmy sprawiać, aby było ich jak najmniej. Pozwoli nam to na szybką weryfikację, czy nie pominęliśmy jakiegoś ważnego fragmentu do poprawy lub napisania.

Komentarze opisujące metodę

Uważam, że metoda powinna sama się opisywać i komentarze tego typu są zbędne. Komentarze nie powinny zdradzać jak zaimplementowana jest funkcja. A przeznaczenie jej powinna zdradzać nazwa. Chęć sprawdzenia jak funkcja się zachowa z odpowiednimi danymi, powinniśmy zaspokoić zerkając na implementację funkcji lub jej testy.

Jednak uważam, że jest jedna okoliczność, kiedy powinny być opisane metody. Jest to publiczne API. Po pierwsze w takim opisie powinno być jasno określone, czego możemy spodziewać się od funkcji (wyjątki itp.). Jednocześnie może być tutaj umieszczona informacja o sposobie użycia. Dlaczego tutaj można stosować (a nawet czasami trzeba) komentarze? Ponieważ jest to deklaracja pomiędzy użytkownikiem, a osobą implementującą tę metodę, jak ona ma się zachowywać. Nie koniecznie programista chce udostępniać źródła swojego API, aby każdy mógł sobie zobaczyć jak to działa. W drugą stronę, osoba używająca frameworku, biblioteki lub systemu z takim API niekoniecznie chce zagłębiać się jak działa dana metoda. Łatwiej jest dla obu stron spisać deklaracje w postaci komentarza, jak zachowuje się dana metoda.

Komentarze typu "why?"

Poznałem już tego typu komentarze. Są one wyjaśnieniem dlaczego problem jest rozwiązany tak, a nie inaczej. Są one często bardzo potrzebne, dla osób, które chcą poprawić kod. Są to właśnie komentarze konieczne. Często spowodowane są źle zaprojektowanych lub napisanym programem, błędami w bibliotekach i innymi tego typu problemami. Czasami coś jest zaimplementowane inaczej niż oczekiwano, czasami dodajemy jakiś dziwny wydający się niepotrzebny kod, który jednak ma swoje znaczenie. Komentarze te są wyjaśnieniem dlaczego tutaj zastosowaliśmy ten mechanizm. Uważam, że nie powinniśmy nadużywać tego sposobu, ale czasem jest na to duża potrzeba.

Podsumowując

Komentarze to zło konieczne. Powinniśmy starać się je eliminować. Czasami są one przydatne, ale to nadal może świadczyć o tym, że coś jest nie tak z kodem. Warto poświęcić czasami czas na zadanie sobie pytania "Czy tym komentarzem nie chce tylko zasłonić złego kodu?".