TL;DR;

Dodawajmy komentarze rozważnie i tylko wtedy, kiedy ich zastosowanie ma sens. Przed dodaniem komentarza przemyśl czy jest on potrzebny czy jest tylko wymówką do nie zmieniania kiepskiego kodu.

Ile razy zastanawialiście się czy komentarz, który piszecie ma sens? A może dodaliście go bo tak każe coding standards przyjęty przez wasz zespół ? Nie jest ważne czy to wymóg formalny czy też coś co chcecie dodać do kodu, ażeby udokumentować jakiś fragment skomplikowanej logiki, może warto by było zastanowić się nad powodami dodawania komentarzy? W mojej dotychczasowej praktyce zazwyczaj dodawałem komentarze, gdyż tak trzeba było. Bo tool do generowania dokumentacji wymaga, bo klient chce takiej dokumentacji, bo tak po prostu ma być. Nie zastanawiając się zbytnio nad zadaniem komentarza. W moim wypadku komentowanie było odruchem. Moje komentarze nie różniły się zbytnio od komentarzy reszty członków zespołu.

Miarka się przebrała…

… a stało się to pewnego wspaniałego dnia, kiedy to przeglądałem pewną klasę DTO. Mała klasa, dosłownie kilka proporcji. Klasa ta wyglądała mniej więcej tak :

Mieliście tak kiedyś ? Przecież te komentarze można by było wygenerować automatycznie. W tym kodzie nie było specjalnych wytycznych co do komentarzy, wszyscy pisaliśmy je automatycznie. Każdy odziedziczył podobny nawyk z poprzednich projektów, gdzie było to wymagane w takiej a nie innej formie. Ale przecież to jest 20 liniowa klasa, a ma w sobie 3 proporcje. Jeśli dodalibyśmy ich jeszcze ze 2 – 3 to już klasa nie mieściła by się na ekranie.

Komentarz remedium na wszystko ?

Wiele osób traktuje komentarze jako remedium na kiepską jakość kodu. Taki złoty środek poprawiający jego czytelność i umożliwiający łatwiejsze przypomnienie sobie o co tak właściwie chodziło. Moim zdaniem dodanie komentarza do kiepskiego kodu nie jest wytłumaczeniem pozostawienia takiego kodu w repozytorium. Kod powinien być czytelny a komentarz powinien co najwyżej wytłumaczyć co się dzieje w skomplikowanych elementach logiki.

Co komentować

Komentować powinniśmy skomplikowane lub też sprytne elementy logiki. Powinny one umożliwić łatwiejsze zrozumienie działania takiego kodu.
Dobrym przykładem mogłyby być skomplikowane zapytania LINQ czy też wyrażenia regularne. Musimy się pogodzić z tym, iż niekiedy mogą taki kod utrzymywać osoby z nieco mniejszą wiedzą od naszej i na pewno wytłumaczenie co się w takim fragmencie dzieje ułatwi im zadanie. Innym zastosowaniem komentarza może być zwrócenie czyjejś uwagi na jakiś ważny aspekt kodu lub zastosowanego rozwiązania. Tutaj przykładem mogą być skomplikowane przekształcenia matematyczne, gdzie wynik otrzymujemy przy wieloetapowych obliczeniach. Odpowiednio dobrany komentarz ułatwi zrozumienie takiego kodu. Tutaj mogę usłyszeć zarzut, że przecież takie wieloetapowe działania można zawrzeć w odpowiednich metodach. Zgadzam się z tym, że można ale czy taka granulacja ma sens, to będzie zależne od indywidualnych potrzeb i tak należałoby to rozpatrywać.

Czego nie komentować

Moim zdaniem nie warto komentować tego co widać na pierwszy rzut oka z samego kodu, a jeśli tego nie widać a widać być powinno to może problemem jest sam kod. Nie powinniśmy też tworzyć changelog-a w komentarzach od tego mamy system kontroli wersji.

Wymagania

Oczywiście w naszej pracy nie wszystko jest takim jakim chcielibyśmy aby było. Niekiedy dodawanie komentarzy jest wymagane przez osoby decyzyjne. W takim przypadku możemy tylko spróbować przekonać taką osobę do naszych racji.