Jak nie komentować kodu

Kilka tldr;

  • Kod sam się komentuje (poprzez odpowiednie nazwy metod i klas, przestrzeganie SRP – klas metody będą niewielkie, korzystanie z ogólnie znanych wzorców)
  • Jeśli powyższe nie wystarcza – ktoś kto nie potrafi zrobić powyższego, wyprodukuje komentarze jeszcze gorszej jakości
  • Jeśli już komentować to nie co i jak robię, tylko „dlaczego” tak robię (np jakaś zewnętrzna – w stosunku do analizowanego kawałka kodu – wiedza) i jest to rzadkie

Komentarze czy raczej dead komentarze

Już kilka razy widziałem wieloletnie projekty w których są komentarze. To się wszystko rozjeżdża po latach i już tylko przeszkadza, utrzymywanie tych komentarzy aktualnych nie jest rozwiązaniem. Prawdziwa masakra, to jest taki dead code. Takie komentarze zamiast dobrej jakości kodu są dodatkowym problemem, a nie rozwiązaniem.

Zakładam, że każdy programista widzi absolutny brak sensu (wartości dodanej) w następującym komentarzu:

/// <summary>
/// Usuwanie oddziału
/// Metoda sprawdza czy dla danego oddziału przypisane są już jakieś konta, jeśli nie, oddział jest usunięty. W przeciwnym wypadku zwracany jest błąd.
/// </summary>
/// <param name="branchId">Id usuwanego oddziału</param>
/// <returns>Zwraca klucz/wartość z wynikiem operacji</returns>
KeyValuePair<bool, string> DeleteBranch(int branchId)

A właśnie takie rzeczy są najczęściej wpychane przez „wymagania klienta”. Btw jeśli traficie do takiego projektu to poproście o dokumentację kodu w formie papierowej, bo chcecie się zapoznać z systemem. Jeszcze nigdy nie widziałem czegoś takiego 🙂

Gdyby jeszcze takie komentarze były neutralne… Ale nie są. Zajmują miejsce na ekranie i czas na analize/scrolowanie ekranem w górę i w dół między aktualnym istotnym kodem.

A jeszcze lepszy jest kod przeplatany takimi wstawkami:

// TODO: czy to nie powinno byc na odwrot
// 01.2010 Tak, chyba pierwsze powinno sie tamto wywołać

// UWAGA! ignorowany wyjatek!

// jksjfalsdj;

// TODO: zalogowac wyjatek  // no i tak wisi kilka lat

// Opisane cos na trzy linijki co w zadnym stopniu nie dotyczy kodu który jest ponizej,
// poniewaz kod juz zostal dawno poprzestawiany, poprzeklejany, kod "zyje",
// a komentarze zostały osierocone

Te opinie nie odnoszą się do bibliotek, frameworków, z których już wiele osób korzysta. Wtedy czasem chcemy je traktować jako zamkniętą całość, bez konieczności zaglądania w bebechy i intellisense działa fajnie. Ale ilu z nas pisze coś takiego???

Zajrzałem też w historię kilku projektów .NET’owych z których korzystam. Najczęściej jest tak, że komentarze metod są dodane dopiero gdy biblioteka jest już stabilna.

Podsumowanie

Prawie nie widziałem komentarzy do metod, które byłyby pomocne (lub pomocniejsze niż kod).

Zaczerpnięte z Kilka słów komentarza o… komentarzach i poparte własnym doświadczeniem wkurzania się na przeszkadzające komentarze.

Reklamy
Ten wpis został opublikowany w kategorii Programowanie i oznaczony tagami , , , . Dodaj zakładkę do bezpośredniego odnośnika.

4 odpowiedzi na „Jak nie komentować kodu

  1. chrisseroka pisze:

    Zgadzam się w 100% chociaż nie pamiętam kiedy ostatnio widziałem komentarze w kodzie. Może są, tylko mózg już je ignoruje :]

  2. k pisze:

    Ogolnie sie zgadzam z brakiem komentarzy ale publiczna metoda jak i kontrakty(interface) powinny byc opisane. Te rzeczy nie powinny sie czesto zmieniać. i dokumentacja pomaga w ich pozniejszym uzywaniu.
    Nie chce szukac implementacji interface i patrzec czy dana metoda może rzucic wyjatek czy nie, czy moze przyjac null czy nie, czy zwraca null czy nie. A już szczególnie gdy mamy kilka implementacji jednego interface. Od tego sa wlasnie opisy metod, aby bylo wiadomo co i kiedy zostanie zwrocone i jak metoda zareaguje na dane wejsciowe.

  3. Może od końca. Gdy masz kilka implementacji danego interface i każda zachowuje się inaczej to masz problem, bo nie tak powinno się korzystać z nich korzystać. Wywołujesz metodę interfejsu i nie wiesz która implementacja się wykona.
    Szczegóły implementacyjne o których piszesz (reakcja na null, rzucane wyjątki) opisane w komentarzu są aktualne tylko w momencie pisania tego komentarza. A nazwa metod interfejsu może mieć np 5 członów, jeśli akurat ma aż tyle odpowiedzialnosci, ale czy to juz nie świadczy ze może za dużo robi?

    • k pisze:

      Pomijam fakt nielogicznego kodu i za duzych interfaców. Zakładam ze kod jest dobrze napisany.
      Dlaczego mamy inaczej traktować kod pisany dla obcych ludzi a inaczej dla członków zespołu ? – „Te opinie nie odnoszą się do bibliotek, frameworków, z których już wiele osób korzysta. ”
      Przychodzi nowa osoba do projektu, nie zna kodu, chce użyc interface IA, i metody A, zwraca ona object, wiec zastanawia sie czy zrobic null check czy nie. No to wchodzi do środka implementacji (dla latwości uznajmy ze jest jedna), w niej mamy odwołania do wielu różnych rzeczy (moze do innych interface, albo serwisy – cokolwiek) i musi czytać kod i szukać czy może on zwrocić null czy nie. Kontakt na interface powinien byc jasny, jakie sa warunki brzegowe dla nulli i wyjatkow, czy masz robic try catch na metodzie czy nie?

      Dodatkowo jest to super narzędzie do pracy ze starym kodem, gdy już poświecisz N czasu na odszyfrowanie co robi dany kod to opisujesz interface/publiczne metody, i nikt wiecej nie musi tam zagladać. A to ze przestają byc zsynchronizowane komentarze z kodem to winna osoby, poprostu code smell. A ponadto kontakty sprawdzamy testami jednostkowymi – aby nie trzeba bylo tego robic w klasach ktore uzywaja danego interface. Zatem skoro sprawdzamy to w testach to dlaczego tego od razu nie opisać.

      I na koniec dodam, że myślę iż duże znaczenie ma nad jak duzym projektem pracujemy. Dla 20tys lini kodu nie napisanie to nie problem, ale dla 200tys juz robi dużą różnice bo nawet jesli cos sami pisalismy to za kilka miesiecy nie bedziemy pamietać.

      PS: nie mialem czasu sprawdzic co napisalem, mam nadzieje ze jest logiczne 🙂

Możliwość komentowania jest wyłączona.