Zakaz umieszczania komentarzy w kodzie

Ktoś kiedyś powiedział, że kod nie powinien zawierać żadnych komentarzy. Jeśli kod był trudny do napisania, to powinien być równie trudny do zrozumienia 🙂 Choć daleko mi do poparcia tej tezy, istnieje inne twierdzenie które znacznie lepiej uzasadnia przymus braku komentarzy…

Trochę czasu minęło od ostatniego wpisu. Z racji zakończenia konkursu „Daj się poznać” (koniec przymusu produkcji min. 2 postów tygodniowo) i wielu nagłych wypadków w życiu prywatnym, nie miałem czasu zaglądać na tę stronę. Jakież było moje zdziwienie, gdy Google Analytics podpowiedziało mi, że jednak znalazł się ktoś kto moje wypociny czyta. Mam nadzieję, że te statystyki to nie wyłącznie boty wyszukiwarek i inne crawlery. Z pewnością nie mam zamiaru pisać, aż tak dużo materiału jak wcześniej, no ale… tak czy inaczej…

Przynajmniej na chwilę 🙂

Bez komentarza

Po przeciwnej stronie barykady, za którą stoją zasady dobrego komentowania, istnieje twierdzenie zupełnie odwrotne – komentarze tylko utrudniają analizę kodu i w ogóle nie powinny być używane. Coś w twoim kodzie wymaga dodatkowego opisu? BŁĄD! To twój kod jest zły i należy go przepisać. Dobry kod to taki, który nie potrzebuje ŻADNYCH komentarzy. Twój kod musi zawierać jakiś nieoczywisty szczegół? Wydziel tę część do osobnej funkcji, którą odpowiednio nazwiesz.

Dla przykładu weźmy napisaną proceduralnie (dla zrozumienia większego grona odbiorców) pseudo-funkcję wykonującą końcowe procesy płatności. W skład tych procesów wchodzi wysłanie e-maila z potwierdzeniem oraz zmiana statusu zamówienia na „opłacone”:

Zły kod:

Nieco lepszy kod:

Co się zmieniło?

Najważniejszą zmianą jest tutaj nazewnictwo funkcji, lepiej odzwierciedlające jej przeznaczenie. To pozwoli nam się pozbyć mini-dokumentacji tuż nad nią. Niemniej istotnym elementem jest też wyciąganie wszelkich stałych argumentów do (najczęściej globalnie) dostępnych stałych. Dzięki temu kod staje się bardziej czytelny i zwykle nie wymaga dalszych komentarzy. Dodatkowo dzięki używaniu stałych globalniej, uzyskujemy możliwość edycji konkretnej funkcjonalności (np. kodu, konfiguracji czy identyfikatora) w jednym miejscu. Krótko mówiąc, nasz kod jest lepszy, ponieważ jest bardziej czytelny i łatwiejszy do analizy. Co z wydajnością, pytasz? Żyjemy w erze gdzie sprzęt jest znacznie tańszy niż czas programisty. Z tego względu czytelny i łatwy do zrozumienia kod jest lepszy od szybszego kodu tak długo, jak koszty jego dalszego utrzymania są niższe, niż cena niepotrzebnie zużywanych zasobów. Z tego powodu programujemy obiektowo w wysokopoziomowych językach zamiast dalej klepać polecnia w assemblerze. Zależnie od używanego języka programowania, można również zoptymalizować działanie kodu (szczególnie kompilowanego) np. przez słowa kluczowe inline i temu podobne rozwiązania. Wracając do tematu – optymalizacje pod względem czytelności, w przeważającej liczbie przypadków, nie wpływają zauważalnie na szybkość wykonywania kodu.

Kiedy brak komentarzy idzie w ekstremizm

Zasada braku komentarzy ma również swoje wady. Jakiś czas temu zostałem poproszony o wymuszenie na kodzie pobierania oryginalnych tłumaczeń angielskich, które są przechowywane tylko w obszarze panelu admina – dajmy mu id 0. Standardowo, w używanym systemie, translacje są pobierane z aktualnie ustawionego publicznego obszaru (obszarów publicznych było kilka, każdy w innym języku). Stanąłem więc przed przymusem edycji czegoś w rodzaju następującego kodu:

Translacje z odpowiedniego źródła „zaciągają się” same. Wystarczy tylko ustawić elementowi obszar, w przeciwnym wypadku automatycznie zostanie wybrany domyślny. Prosta zmiana i gotowe:

Czy aby na pewno? Pierwszym krokiem w świetle tego co pisałem wcześniej należałoby wyciągnąć „0” do stałej. Jako, że nie było w kodzie publicznie dostępnej stałej zawierającej id obszaru panelu admina, utworzyłem nową.

Nadal jednak nie jest to kod zadowalający. Wyobraźmy sobie, że inny programista widzi tę linijkę i głowi się: No ale dlaczego pobiera translacje konkretnie z obszaru panelu admina? Aby uniknąć tego problemu, zgodnie z powyższą zasadą należałoby utworzyć dodatkową metodę z adekwatną nazwą:

Czy to uniwersalny kod? Moim zdaniem nie do końca. Nie zawsze angielski musi być domyślnym językiem dla panelu admina. Można nazwać metodę bardziej uniwersalnie (i jeszcze dłużej) getElementWithDefaultLanguageForAdminPanel() co dalej nie jest wyczerpującym wyjaśnieniem. Można starać się dalej poprawiać to rozwiązanie na wiele sposobów lub po prostu dodać linijkę komentarza:

Które rozwiązanie jest w tej sytuacji lepsze, pozostawiam do samodzielnej oceny.

Podsumowanie

Moim zdaniem obie teorie mają swoje zalety i wady, więc należy zachować umiar w balansowaniu między nimi. Ważniejsze jest jednak, by utrzymać spójność stylu, w jakim pisany jest dany projekt, chyba że dostaniemy inne polecenie (np. refaktoryzacja). Dla przykładu, jeśli dołączamy do projektu, gdzie w kodzie używany jest javadoc, czy jego odpowiednik dla dowolnego innego języka, powinno się dostosować swój kod tak, aby nie odstawał od reszty. Dzięki temu zobaczenie kawałka kodu może dać dość dobre wyobrażenie o ogólnym stanie projektu a wszelkie odstępstwa będą (zazwyczaj) niemiłą niespodzianką.