Witaj na Zine.net online Zaloguj się | Rejestracja | Pomoc

Czy komentarze to przeżytek?

A' propos tematu komentarzy postu Szymona i uwag do tego postu, chciałam dodać swoje trzy grosze...

Nie tak dawno temu byłam świadkiem kształtowania się idei i powstawania zbioru reużywalnych bibliotek. Przy okazji tej inicjatywy podjętych zostało kilka decyzji. Czy chodziło o to by w końcu było porządnie? - nie wiem. Na pewno rozpoznawano i zaproponowano wiele technologii, nowych i starych podejść do tworzenia oprogramowania oraz metodyk, ktore nie istniały w szeroko pojętym użyciu.

Pomijając fakt sensowności budowania własnych bibliotek, inicjatywa spowodowała, iż stało się wiele dobrego, np. w końcu zaczęto używać integration buildów, developerzy uslyszeli w końcu i nawet byli skłaniani do pisania testów. Ale sprawa, o której chcę napisać dotyczy decyzji o wymagalności spełniania reguł sprawdzających napisany kod. Zwłaszcza jedna kwestia wydawała się dość kontrowersyjna - reguły wymagalności istnienia komentarzy.

W związku z tym rozgorzała dyskusja, w trakcie której ścierały się dwa obozy. Podobno chodziło im o to samo - o większą czytelność kodu. Oto argumenty obu stron:
Team 1: Komentarze wprowadzają wyjaśnienia do kodu, więc są nie tylko przydatne, ale również niezbędne. Jeśli kod jest źle napisany - musi być skomentowany lub poprawiony. Jeśli kod jest napisany dobrze - w komentarz powinien po krótce opisywać odpowiedzialność klasy, to co robią metody, jakie przyjmują argumenty, jakie pola i wlasności posiada klasa.
Team 2: Potrzeba komentowania kodu wskazuje, że jest on źle napisany. Zamiast komentarzy piszmy kod dobrze.

IMHO  żadna z tych skrajnych opinii nie jest do końca słuszna. Zgodzę sie oczywiście, że w idealnym świecie, z idealnym kodem (i z idealnym leżakiem dla mnie na idealnej plaży w Santa Monica) komentarze są zbędne. Zgodzę się, że idealnie napisany kod ich nie potrzebuje, ale... czy ktoś kiedyś widział idealny kod? Nie twierdzę jednak, iż komentarze nie są potrzebne, by wyjaśnić to, co nie jest jasne. No i oczywiście w całej aferze komentarzowej chodziło również o mozliwość generowania dokumentacji.
 
I tak wracamy do idei bibliotek firmowych... Osoby podejmujące decyzje należały do pierwszego obozu, więc reguły nakazywały by istniały komentarze dla każdej klasy, dla każdej metody, dla każdej własności i dla każdego pola klasy. Co z tego wyniknęło prócz kłótni? Zobaczmy...

Komentowanie wszystkiego

Ciekawa sprawa - komentarze dobrze napisanego kodu są nie tyle złe, co dość zabawne. Oto kilka znalezionych przykładów:

/// <summary>
/// Klasa reprezentująca atrybut.
/// </summary>
public class Attribute
{
 ...
   /// <summary>
   /// Dodaje atrybut.
   /// </summary>
   /// <param name="attribute">Atrybut.</param>
   public void AddAttribute(Attribute attribute)
   {
      ...
   }
   ...
   /// <sumary>
   /// Nazwa atrybutu.
   /// </sumary>
   public string AttributeName
   {
    get;set;
   }
}


Przydatne te komentarze, nieprawdaż?
Można sobie wyobrazić ile roboty jest z ich pisaniem - dokładnie, tyle ile wynosi wymyślenie i napisanie komentowanego właśnie kodu. Efekt to zero przydatnych informacji i trochę smiechu przy czytaniu. Oczywiście jeszcze zabawniej byłoby gdyby na dodatek zarówno nazewnictwo kodu jak i komentarze były w języku angielskim - w tej sytuacji mamy niemalże translator :D
W tym miejscu warto wspomnieć o kolejnej regule która sprawdzała istnienie kropki na końcu komentarza, więc aby zdanie nie posiadało jednego tylko słowa, niektórzy deweloperzy zmieniali "Atrybut." na "Dodawany atrybut." :D Zadziwiało mnie w imię czego występowało takie poświęcenie i jak niedoceniani byli ci cisi bohaterowie :)

Komentowanie złego kodu
Jeśli chodzi o metody, które wymagają komentarzy (dla zrozumienia tego, co robią) radziłabym mieć ciągle z tyłu głowy dwie sprawy. Po pierwsze należy się zastanowić czy komentowanie kodu nie zajmie nam więcej niż jego poprawienie, a po drugie (jeśli odpowiedź na pierwsze pytanie to 'nie' i jednak decydujemy się na komentarz) zaplanować ten refaktoring w przyszłości.
Jesli wyjaśnienie dotyczy zawartosci metody, opisu klasy, ktora zostala napisana w niezrozumiały sposob, to kilka zdań nie zaszkodzi, a moze pomóc. Jesli natomiast komentarz dotyczy tego by po krótce przedstawić nagłówek, to moze warto zastanowić się nad zmianą jej nazwy na bardziej sugestywną - to może wystarczyć.

Muszę jeszcze dodatkowo ostrzec przed tym, by zbytnio nie ufać narzędziom. Sprawdzały one jedynie istnienie komentarzy, które nagminnie wystepowały w nastepujacych formach:
- Nie mam czasu komentować.
- Póżniej to skomentuję.
- Tralalalala...
- Itd.
Prawdę mówiąc widząc to nie zdziwilabym sie gdyby gdzieś tam istniały jakies nieprzyzwoite slowa, skoro nikt nie bał się w ten sposób spelniać narzuconych wymagań :D

Komentowanie metod w klasach dziedziczących
Kolejny problem pojawił się również z winy narzędzia. Otóż klasa implementujaca interfejs (lub dziedzicząca metody innej klasy) nie dziedziczyla dokumentacji znajdującej się w komentarzach. Aby więc spelnić wymagania nalezało skopiować te komentarze lub uzyc R# (co sprowadza sie do rozwiazania pierwszego). Osobiście odczułam to boleśnie, bo akurat w moim przypadku sprowadzalo sie to do wielu godzin bezsensownej pracy.

Najśmieszniejsze, że jednym z zamysłów budowy bibliotek było chowanie wszystkiego za interfejsami. Pomysł zacny - tworzymy swoistego rodzaju adaptery, natomiast w aplikacji konfigurujemy tylko której implementacji uzywamy i voila, wszystko ma hulać.
Dokumentacja jaką widzi użytkownik biblioteki to jedynie dokumentacja interfejsu. Teoretycznie nie powinien nigdy używać klas implementujących, a juz na pewno nie operatora new :D Tak wiec... po co mu ta odziedziczona dokumentacja?

Konkludując - błędem jest zakładanie, że kod nie potrzebuje komentarzy, ale jeszcze większą pomyłke robi się zmuszając do komentowania wszystkiego. Jest to strata czasu, a efekty są marne. Same komentarze w takiej sytuacji nie ułatwiają zrozumienia niczego, nawet pomijając fakt, że ludzie w sytuacji kiedy się ich do czegoś zmusza, nie zrobią ich porządnie. W czasach intellisense użytkownicy nie czytają dokumentacji - liczą na sugestywne nazwy klas, metod i własności. To właśnie poprawia jakość kodu i dostatecznie wyjaśnia im jak używać danej biblioteki.
Komentarze nagłówkowe to przeżytek. Komentarze wewnątrz metod natomiast to ryzykowna sprawa... Mogą pomoc w zrozumieniu zawartości, ale najczesciej są zrozumiale jedynie dla autora, na dodatek w momencie ich tworzenia. Z biegiem czasu tracą na aktualnosci, inni boją sie je usunać i powstaje swoistego rodzaju bałagan.
Apeluję więc by developerzy jeśli już piszą konmentarze odnosili się do nich jak do kodu. Mimo braku automatycznego sprawdzania ich składni, by pisali je dobrze, zrozumiale oraz tak, by były one naprawdę pomocne. W innym wypadku nie mają większego sensu.
Opublikowane 10 grudnia 2009 21:59 przez fusion
Filed under: ,

Komentarze:

11 grudnia 2009 07:57 by simon

# re: Czy komentarze to przeżytek?

Zgadzam się z _prawie_ wszystkim:) Oto, dlaczego "prawie":

"Komentarze nagłówkowe to przeżytek."

Wg mnie Darek słusznie w komentarzach do mojej notki zauważył, że w przypadku reużywalnych (:P) bibliotek klas komentarze XML są pomocne, choćby przy generowani dokumentacji a'la MSDN. Zgadzam się z nim.

"Nazwa atrybutu." (code sample)

Zastosowałaś bardzo zły zwyczaj praktykowany w naszej (właściwie mojej:P) firmie. Powinno byż "Zwraca nazwę atrybutu". Dlaczego? Bo w intellisense od razu widać, czy mam do dyspozycji tylko get, czy get i set. Bardzo lubię ten ficzer, bo sprawdzenie czy mogę ustawić dane property zajmuje chwilę i wybija z rytmu pracy.

"Komentarze wewnątrz metod natomiast to ryzykowna sprawa..."

Każdy komentarz wewnątrz metody da się zamienić na komentarz XML nad wydzieloną metodą. To udowodnione:P Prowadzi to do ciekawej konkluzji: bardziej przydatne są komentarze XML nad metodami prywatnymi, niż publicznymi!

-------------------------

Zgadzam się, że kopiowanie komentarzy do klas dziedziczących to jest jakiś dramat. To gorsze niż kopiowanie kodu. Powinni za tu urywać dowolnie wybrane dostępne części ciała.

Dodam jeszcze swoje 3 grosze: utrzymywanie komentarzy jest trudniejsze niż utrzymywanie kodu, ponieważ kompilator nie sprawdza ich poprawności/aktualności. Jeśli mamy więc 5 linijek metody i 5 linijek komentarza XML, to tak, jakbyśmy mieli na utrzymaniu 15 linijek kodu. Każda linijka kosztuje X $/miesiąc...

11 grudnia 2009 10:29 by dotnetomaniak.pl

# Cold Fusion : Czy komentarze to przeżytek?

Dziękujemy za publikację - Trackback z dotnetomaniak.pl

12 grudnia 2009 22:05 by arkadiusz.wasniewski

# re: Czy komentarze to przeżytek?

Dorzucę swoje trzy grosze...

Prawda jest taka, iż zawsze trzeba znaleźć "złoty środek". I prawie zawsze będzie on gdzie indziej. Jeden z moich projektów służy do obsługi komunikacji z drukarką fiskalną. Kod powstał na podstawie dokumentacji dostarczonej przez jednego z podmiotów zaangażowanych w zbudowanie tego urządzenia. Bardzo duża liczba komentarzy do metod przekracza kilkanaście linii. Przykładowo metoda ustawiająca tryb obsługi błędów po stronie drukarki ma 38 linii komentarza włączając w to znaczniki xml. Poza informacją o wybranym trybie obsługi błędów jest również opis sytuacji wyjątkowych z punktu widzenia architektury urządzenia, sytuacje kiedy drukarka resetuje wybrany rodzaj obsługi błędów itp. Teoretycznie większość tych informacji można znaleźć w różnych częściach dokumentacji. Część z nich natomiast jest wynikiem przeprowadzonych empirycznie wydruków (opóźnienia w milisekundach, czasy oczekiwania...). W takim projekcie samo nazewnictwo metod to za mało.

21 grudnia 2009 11:20 by fusion

# re: Czy komentarze to przeżytek?

Może dlatego uważam, że komentarze nagłówkowe to przeżytek, bo nie wierzę w reaużywalne biblioteki. A nawet jeśli wierzę, to i tak wolę sugerowac się przy ich użyciu sugestywnymi nazwami niz dokumentacją, która często nie mówi nic, a w najlepszym przypadku to samo co nazwa.

Jeśli chodzi o komentarz do własności AttributeName, to przykład posiada zarówno get jak i set, a dodatkowo pochodzi z wyżej wspomnianej firmy :)

A generalnie zgadzam się z ideą złotego środka i nie mówię, że komentarze są złe same w sobie. Są po prostu nieumiejętnie używane i nadużywane. Natomiast w przypadkach, gdy naprawdę by się przydały, (często z lenistwa) pomijane.

Komentarze anonimowe wyłączone