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.