Programiści dzielą się na:
Jednak, ostatnio dwa zdarzenia spowodowały, że częściowo przewartościowałem swój sposób patrzenia na tę sprawę i moje nastawienie przesunęło się znacząco w kierunki nie pisania komentarzy. Co to za zdarzenia? Po pierwsze postanowiłem wrócić do swojego starego projektu napisanego w C# ponad 3 lata temu. W skrócie program realizuje wnioskowanie wstecz. Właściwy silnik wnioskujący ma około 800 linii kodu (nie licząc GUI i definicji prostych struktur danych). Przy czym ponad połowa z tego przypada na komentarze, definicje regionów i znaki nowe linii! Problem w tym, że pomimo dużej liczby komentarzy miałem dużą trudność w zrozumieniu tego kodu i niektórych rozwiązań jakie przyjąłem. Drugie zdarzenie dotyczyło cudzego kodu, w którym skomentowana była prawie każda linijka. Początkowo myślałem, że ułatwi to sprawę ale myliłem się. Tak duża liczba komentarzy skutecznie utrudniała zrozumienie kodu. Usunięcie znaczącej części tych komentarzy (i refactoring) sprawiło, że kod stał się dużo łatwiejszy w odbiorze.
W obecnej chwili uważam, że większe znaczenie ma odpowiedni podział kodu na klasy, a przede wszystkim na metody. Zamiast komentarza lepiej zamknąć kod, którego dotyczy w metodę o samo tłumaczącej się nazwie. Komentarze w kodzie staram się ograniczyć do miejsc, które rzeczywiście tego wymagają: skomplikowany algorytm, szybko wprowadzane poprawki itd. Jeśli chodzi o komentarze do metod to uważam, że są one niezbędne tam gdzie z nazwy metody i nazw jej parametrów nie można wywnioskować jej przeznaczenia. Jeśli mamy skłonność to niepisania komentarzy to warto spytać innego programisty co jego zdaniem robi dana metoda. Jeśli odpowie poprawnie to komentarz z dużym prawdopodobieństwem nie jest potrzebny. Komentarz jest również potrzebny jeśli metoda rzuca jakieś wyjątki. Co jednak z metodami publicznymi i chronionymi czyli tymi, z których potencjalnie będą korzystać inni. Tutaj mam mieszane uczucia. Z jednej strony dobra praktyka mówi, że dla tych metod komentarze są potrzebne. Z drugiej po co komentować metodę o takim nagłowku IList<User> GetAllUsersWithBankAccount(), która zwraca listę użytkowników z kontem bankowym?
- Tych, którzy piszą bardzo dużo komentarzy, czasami prawie w każdej linijce. Tych spotkałem niewielu.
- Tych, którzy w ogóle ich nie piszą, nawet jeśli napisali kod, którego nie da się zrozumieć bez choćby odrobiny komentarza. Tych ortodoksów jest już więcej.
- Największa grupę stanowią natomiast programiści, którzy sytuują się gdzieś pomiędzy tymi dwiema skrajnościami.
Jednak, ostatnio dwa zdarzenia spowodowały, że częściowo przewartościowałem swój sposób patrzenia na tę sprawę i moje nastawienie przesunęło się znacząco w kierunki nie pisania komentarzy. Co to za zdarzenia? Po pierwsze postanowiłem wrócić do swojego starego projektu napisanego w C# ponad 3 lata temu. W skrócie program realizuje wnioskowanie wstecz. Właściwy silnik wnioskujący ma około 800 linii kodu (nie licząc GUI i definicji prostych struktur danych). Przy czym ponad połowa z tego przypada na komentarze, definicje regionów i znaki nowe linii! Problem w tym, że pomimo dużej liczby komentarzy miałem dużą trudność w zrozumieniu tego kodu i niektórych rozwiązań jakie przyjąłem. Drugie zdarzenie dotyczyło cudzego kodu, w którym skomentowana była prawie każda linijka. Początkowo myślałem, że ułatwi to sprawę ale myliłem się. Tak duża liczba komentarzy skutecznie utrudniała zrozumienie kodu. Usunięcie znaczącej części tych komentarzy (i refactoring) sprawiło, że kod stał się dużo łatwiejszy w odbiorze.
W obecnej chwili uważam, że większe znaczenie ma odpowiedni podział kodu na klasy, a przede wszystkim na metody. Zamiast komentarza lepiej zamknąć kod, którego dotyczy w metodę o samo tłumaczącej się nazwie. Komentarze w kodzie staram się ograniczyć do miejsc, które rzeczywiście tego wymagają: skomplikowany algorytm, szybko wprowadzane poprawki itd. Jeśli chodzi o komentarze do metod to uważam, że są one niezbędne tam gdzie z nazwy metody i nazw jej parametrów nie można wywnioskować jej przeznaczenia. Jeśli mamy skłonność to niepisania komentarzy to warto spytać innego programisty co jego zdaniem robi dana metoda. Jeśli odpowie poprawnie to komentarz z dużym prawdopodobieństwem nie jest potrzebny. Komentarz jest również potrzebny jeśli metoda rzuca jakieś wyjątki. Co jednak z metodami publicznymi i chronionymi czyli tymi, z których potencjalnie będą korzystać inni. Tutaj mam mieszane uczucia. Z jednej strony dobra praktyka mówi, że dla tych metod komentarze są potrzebne. Z drugiej po co komentować metodę o takim nagłowku IList<User> GetAllUsersWithBankAccount(), która zwraca listę użytkowników z kontem bankowym?
orcid.org/0000-0002-6838-2135
8 comments:
Ja mam ostatnio podobne przemyślenia. Częściej w przypadku, gdy po długim debugowaniu okazuje się, że pominąłem pewien przypadek i wystarczy dopisać jedną/dwie linijki, żeby zadziałało. Wydaje się, że w tym przypadku ZAWSZE warto dodać komentarz po cóż to ta linijka własnie tam jest. Z drugiej strony czasem warto akurat wtedy zrefaktoryzować kod i wrzucić to do jednej opisującej się metody (choć nie zawsze to najlepsza droga...)
A jednolinijkowe komentarze są IDEALNE (i raczej tylko wtedy), gdy uczysz się jakiejś technologii od zera, przeglądając wzorcowy kod:)
Kiedyś też byłem zwolennikiem komentarzy, ale raczej były mi one potrzebne do automatycznej generacji plików pomocy do bibliotek dostarczanych do klientów, raczej nigdy nie postrzegałem ich jako elementów objaśniających działanie kodu. Teraz wymagam, aby praktycznie komentarzy w kodzie nie było - jeżeli coś wymaga komentarza, to najczęściej jest to kandydat do przepisania (komentarze zdarzają się tylko przy niektórych algorytmach). Zdecydowanie polecam książkę "Czysty kod. Podręcznik dobrego programisty" Boba Martina oraz zapoznanie się z samą ideą "czystego kodu".
Ja również jestem zdania, że kod ubrany w odpowiednie klasy i metody wystarcza do zrozumienia całości. Często jest tak, że funkcjonalność danej metody jest tak oczywista, że przeglądanie kodu jest marnotrawstwem czasu.
A jakie są Wasze doświadczenia z komentarzami w dużych, długo trwających projektach (setki tysięcy/miliony linii kodu), w których bierze udział wielu programistów? Czy są potrzebne (przynajmniej w publiczny API)? Czy zamiast komentarzy wystarczą dobrze napisane testy jednostkowe? Czy stosowaliście diagramy UML?
Komentarze są jednak bardzo potrzebne, jeśli nazwy metod i zmiennych zawierają specyficzne dla dziedziny pojęcia. Na przykład, ilu programistów wie, że „endowment” to ubezpieczenie nażycie i dożycie? Dobre IDE może wyświetlać komentarze przy najechaniu myszką lub kliknięciu na nazwę metody. To bardzo pomaga, przy zrozumieniu kodu, który składa się praktycznie tyko z wywołań metod.
"Na przykład, ilu programistów wie, że „endowment” to ubezpieczenie nażycie i dożycie?"
Powinni wiedzieć wszyscy pracujący przy projekcie.
Ja komentarze piszę tylko wtedy kiedy trzeba wyjaśnić _po co_ (_dlaczego_) coś tak zostało zrobione, a nie _jak_.
Poza tym komentarze: często kłamią, nikt ich nie utrzymuje.
np. taki komentarz: //pobieranie struktury z bazy danych
i pod nim pięć linii
zamieniamy na funkcje: GetSchema lub GetDBSchema (w zależności od konwencji). Dodatkowo dajemy trochę możliwości sprawdzenia kompilatorowi.
"tą sprawę" kłuje mnie w oczy
(powinno być tę sprawę)
mn
Widzę, że zawarto tu sporo spośród tego, co mnie ostatnio na tyle gryzło, że spisałem swoje wizje :)
http://www.yarpo.pl/2011/10/24/komentarz-martwy-kod-o-ktory-trzeba-dbac/
Cieszę się, że mam podobne odczucia :)
@Michał Komorowski:
Nie miałem okazji pracować z wielomilionoliniowym kodem, jednak z takim posiadający kilka lat, ślady wielu programistów oraz klasy po 8 000 (słownie: 8 tysięcy) linii, niestety, tak. Czasem metody miały po 700 i więcej linii, co sprawia, że całkowicie nie da się już panować na tym kodem.
Dodatkowo wszędzie po kodzie rozsiane były zmienne globalne, co znacznie utrudniało (uniemożliwiało) refaktoryzację (chyba, że ktoś przekonałby szefów, że należy napisać to od nowa). W takim kodzie komentarze także na niewiele się zdają, gdyż:
[quote="piotrb"]Poza tym komentarze: często kłamią, nikt ich nie utrzymuje.[/quote]
Z relacji wielu znajomych wynika, że niestety, w większości firm takie aspekty jak zarządzanie jakością kodu jest spychane w priorytetach bardzo daleko w dół.
Post a Comment