Komentarze? Tylko pod wpisem, nie w kodzie:)

na początek

Na początku był kod. Kod, który się rozrastał, żył, ewoluował, a pracę nad nim wykonywało programistów wielu. I kod ten spełniał swoje zadanie. I nigdy nie dotknął go zbędny proces refaktoryzacji, co pozwoliło, że rozmiary jego były naprawdę okazałe, jego możliwości - mnogie, a czytelność - żadna.

"Na szczęście", w trakcie pracy nad kodem, wielu programistów, którzy mieli z nim do czynienia, otaczali kolejne linijki instrukcji, pokaźną ilością komentarzy, które miały na celu przekazać przyszłym pokoleniom tajemnice zawarte w kodzie i uzmysłowić jego działanie.

co było dalej?

Pewnego dnia, nowy programista, miał za zadanie wprowadzić kolejne modyfikacje w tym kodzie. Jakie było jego zdziwienie, gdy okazało się, że wewnątrz metod klasy było więcej komentarzy niż instrukcji. Były nawet zakomentowane stare fragmenty kodu z dopiskiem: "Może kiedyś się przyda" :)

Nim przeczytał wszystko i doszedł do tego, które komentarze i zmiany były wcześniej, a które później, minęło sporo czasu. Niestety jego wiedza na temat funkcjonalności, którą miał modyfikować była nadal żadna, do tego w głowie kotłowało mu się sto tysięcy, niekiedy sprzecznych, informacji, na temat tego co, gdzie, kiedy i dlaczego? I czy te zakomentowane kawałki kodu rzeczywiście mogły się jemu (lub komukolwiek) kiedyś przydać?

A jeszcze nawet nie przebrnął przez właściwy kod!

komentarze poprawiają czytelność?

Nic bardziej mylnego. Dobrze przemyślany kod, o który się dba i w razie potrzeby - refaktoryzuje, klasy z odpowiednimi zależnościami, nie potrzebują komentarzy.

I zazwyczaj kiedy się one pojawiają, przeszkadzają zamiast pomagać, odciągają uwagę od rzeczy istotnych.

nie komentuj starego kodu

Po co komentować stary kod? Bo może się przydać? Bo był fajny i szkoda go wyrzucać? Jakikolwiek powód by nie był, pozostawienie starego kodu w postaci komentarza nie ma najmniejszego sensu. Po to są systemy kontroli wersji, aby w każdej chwili można było dotrzeć do kodu, który kiedyś istniał.

Pozostawianie tych zbędnych linii, sprawia, że kiedyś Ty bądź koledzy z zespołu będą zmuszeni przedzierać się przez niego i zastanawiać się, jakie były motywy postępowania osoby, która tego czynu się dopuściła. I najgorsze, jeżeli osoba pracująca nad nim (kodem) po Tobie, dojdzie do wniosku, że "ja to na wszelki wypadek zostawię".

komentowanie kroków w metodach

Niekiedy zdarza się, że metoda, z którą mamy do czynienia ma setkę lub, broń Boże, więcej linii kodu! Co wtedy? Komentarz pasuje jak ulał, żeby opisać kolejno wykonywane kroki, czyż nie?

Nie. Skoro kroki są na tyle duże i skomplikowane i/lub jest ich tak wiele, że zastanawiasz się nad dodaniem stosownych komentarzy, to pora aby rozbić metodę na mniejsze części. Prywatne metody to naprawdę wspaniała rzecz i dzięki nim Twój kod pozostanie czytelny i prostszy do zrozumienia. Jeżeli uważacie mimo to, że logika stojąca za taką metodą jest warta opisania, to możecie dodać odpowiedni komentarz do metody, a nie w jej ciele.

Czasami zdarzają się sytuacje, że metod jest już tyle, że z przerażeniem decydujecie się na stworzenie kolejnej. W takim wypadku najwyższy czas na refaktoryzację, bo bardzo prawdopodobne, że Wasza klasa została obarczona zbyt wielką odpowiedzialnością.

to po co komuś komentarze?

Aby opisać atrybuty i metody klasy. Aby opisać samą klasę itp.

Komentarze nie powinny być wykorzystywane do tłumaczenia kodu metod. Od tego mamy diagramy i dokumentację, dlatego mamy możliwość tworzenia metod prywatnych, dlatego powinniśmy pamiętać o dobrych, opisowych nazwach dla atrybutów, metod, zmiennych itp.

Zdaję sobie sprawę, że pewnie zdarzają się wyjątki od tych reguł lub z różnych powodów decydujemy się na ich złamanie. W takich sytuacjach warto pamiętać o kilku rzeczach: komentarz nie powinien zaciemniać kodu, nie powinien utrudniać jego zrozumienia, nie powinien skupiać na sobie całej uwagi. Powinien być on podpowiedzią, jak najmniej inwazyjną, nie powinien być główną treścią, na której się zatrzymujemy.

A najlepiej to wyjść z założenia, że komentować to można artykuły na blogach, a nie kod:D