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

Simon says...

Szymon Pobiega o architekturze i inżynierii oprogramowania
Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze
Komentarze w kodzie metod pomagają nam zrozumieć, co miała na myśli osoba implementująca algorytm realizowany przez daną metodę: dlaczego ten if wygląda tak i po co jest ta pętla. Komentarze pozwalają też na oznaczenie etykietami pewnych logicznych fragmentów metody, które stanowią spójną całość. Takie fragmenty są też często zamykane w regiony.

Zarówno komentarze, jak i regiony, wewnątrz metod są znakiem, że kod potrzebuje refaktoryzacji. Sam z siebie jest nieczytelny, dlatego my, mądrzy deweloperzy, szukamy innych sposobów na uczynienie go czytelnym – stosujemy więc komentarze i regiony. Zamiast tego powinniśmy zastosować refaktoryzację polegającą na wydzieleniu metody (i nadaniu jej nazwy, która będzie na tyle ekspresyjna, aby wyjaśniała cel logiki znajdującej się wewnątrz). Pod koniec pierwszej dekady XXI wieku nie musimy się już martwić kosztem wywołania metody.

Następnym razem, gdy zobaczysz w kodzie metody komentarz/region zastanów się, czy jest on tam niezbędny. Czy nie lepiej wydzielić metodę?

Opublikowane 3 listopada 2009 18:10 przez simon

Filed under:

Komentarze:

# Simon says... : Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 3 listopada 2009 19:37

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

dotnetomaniak.pl

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 3 listopada 2009 19:57

i dobrze mówi. Gdzie tu kontrowersja?

Ja sie też mogę pod tym podpisać.

Krzysztof Koźmic

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 3 listopada 2009 21:24

Wszystko co napisane - jak najbardziej. I wiele wiecej. Ja bym do tego dorzucił również inne rodzaje komentarzy - w bardzo wielu przypadkach jedyne co robią to zwiększają objętość kodu oraz ulegają desynchronizacji wprowadzając przyszłego czytelnika w błąd.

Co daje komentarz tutaj?

///<summary>

///Gets user by id.

///</summary>

///<param name="userId">Id of the user</param>

///<returns>User with given id.</returns>

public User GetUserById(int userId)

{

return dataAccess.GetUserById(userId);

}

Jajco, a bardzo często się z takimi komentarzami spotykałem.

Potwory w stylu GhostDoc - do piekła :). Jeśli nazwa metody nie mówi co owa metoda robi to trzeba zmienić nazwę metody a nie dodawac przynajmniej 3 dodatkowe linie zbednego kodu w postaci komentarza.

Procent

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 4 listopada 2009 07:05

@Krzysztof

Masz racje, że ta seria schodzi na psy (jeśli chodzi o kontrowersyjność). Muszę się bardziej postarać:)

@%

Szczerze Ci powiem, że o tym nie pomyślałem. Jakoś tak mi utkwiło, aby komentować wszystko co publiczne (z tym, że komentuje zwykle sensownie). Muszę sobie sprawdzić w żywym projekcie, czy to rzeczywiście niezbędne:)

simon

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 4 listopada 2009 11:41

Sprzeciw!

1. Komentarze mogą się przydać osobą, które przyjdą do pracy i będą musiały pracować z naszym kodem. Nie każdy musi mieć podobny tok myślenia do naszego. Często wydaje się nam, że coś jest proste, to g... prawda.

2. Komentarze metod w stylu "Gets Id", "Returns integer" są bez sensu. Ale tu nie jest mowa o bezsensownych komentarzach, a o tym że są złe w ogolności - co jest bzdurą.

3. Komantarze muszą być pisane, jeśli dokumentację do kodu (niekoniecznie sam kod) chcemy przekazać komuś dalej. Np. tworzymy moduł do wysyłania maili i dystrybuujemy nasz muduł bez kodu źródłowego. Jak niby ktoś ma z tego postem skorzystać? Ma odpalić reflektora i jazda?

Po co murarzowi plan, skoro wiadomo, że tu ma być ściana, tam ma być belka itd. Przecież to dla niego jasne, a jednak korzysta on z dokumentacji projektowej. Po co protokół odbiorczy skoro chałupa stoi i ma sie dobrze?

Bez przesady panowie.

Darek Tarczynski

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 4 listopada 2009 15:00

@Darek

1. Czy komentarze w kodzie pomogą w takim wypadku? Ja nie przypominam sobie kawałka kodu, w którym chciałbym zobaczyć komentarz, a jednocześnie nie miałem kilku pomysłów na jego refaktoryzację

2. Komentarze wewnątrz kodu metody są złe - to moje stwierdzenia. Jeśli dobrze zrozumiałem Procenta, miał na myśli, że komentarze XML są często źle wykorzystywane oraz czasem pozbawione sensu. Kiedy? Jeśli ich treść wynika wprost z nazwy metody i (podkreślić) rozważana klasa nie jest przeznaczona do zapakowania w DLLkę i rozpowszechniania.

3. Masz racje, jeśli DLLkę upubliczniamy, komentarze (XML-owe) być muszą. Wraz z dokumentacją wygenerowaną np. przez SandCastle.

simon

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 4 listopada 2009 16:02

@simon

1, 2: Komantarze w kodzie pomogą zrozumieć ideę pewnej części programu. Nie wiem dlaczego miałoby to być złe. Tak jak napisałem, komuś może to pomoć potem. Jasne, może sobie odpalić debugger i zobaczyć co i jak, ale nie w tym problem. Stosujesz np. gdzieś w metodzie skrót z funkcji SHA256, a nie MD5: napisz dlaczego. Być może wymaga tego np. polityka bezpieczeństwa firmy, być może coś innego - nie każdy musi to wiedzieć, nie każdy jest w projekcie od początku. To jeden z wielu przykładów.

Darek Tarczynski

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 4 listopada 2009 16:16

@Darek

Na początek małe info, żeby było jasne. Notki i moje poglądy są umyślnie kontrowersyjne.

Mimo iż zgadzam się z Tobą, że komentarze _czasem_ są sensowne, nie powiem tego głośno, aby w ten sposób nie zachęcać do ich pisania.

Może powinienem wyrazić się precyzyjniej. Komentarze w kodzie często są wymówką, aby zostawić metodę

a) zbyt długą--komentarze dzielą metodę na logiczne sekcje

b) zbyt skomplikowaną (w sensie cyclomatic complexity)--komentarze opisują przepływ sterowania

W tych wypadkach są złe i tej wersji będę się trzymał.

Jeśli chodzi o przykład, który przytoczyłeś: komentarz jest OK, ale w tym (konkretnym) wypadku wolałbym (gdyby to był mój projekt), aby ta informacja znalazła się w komentarzu XML opisującym całą metodę.

simon

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 4 listopada 2009 16:30

Komentarze XML mają charakter bardziej ogólny, służą do wygenerowania wspomnianej dokumentacji i przekazania jej klientowi. Nie koniecznie powinny zawierać szczegóły implementacyjne, chyba że są to np. przykłady użycia "sample". Metody prywatne, których nie będziemy wywoływać spoza modułu w moim przekonaniu mogą, ale nie muszą posiadać komentarzy XML, ale POWINNY zawierać komentarze w kodzie.

To takie moje uwagi (skoro termat został poruszony), abstrahując od zamierzenia autora tej notki :-)

Darek Tarczynski

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 4 listopada 2009 22:29

Widze ze decyzja troche zmierza w kierunku dywagacji nt wyzszosci marchewki na rzodkiewka, ale co mi tam.

Z mojego doswiadczenia dokumentacja xmlowa dla klienta jest warta mniej niz papier na ktorym ja drukujesz, (chyba ze piszesz framework).

Dokumentacja w kodzie jest warta jeszcze mniej, z calego szeregu powodow, z ktorych Szymon wymienil najwazniejsze wiec nie bede sie po nim powtarzal.

To ze komentarze pomagaja zrozumiec idee programu - tak, ale lepsza do tego celu jest dobra struktura samego kodu.

Twoj przyklad, Darku, z algorytmem do hashowania jest tego swietnym przykladem.

Developer odwolujac sie do niego wprost pewnie bedzie czul ze cos jest nie tak, i aby uspokoic sumienie napisze dwa zdania za podwojnym slashem o tym jakie to wazne i wielkopomne rzeczy wlasnie sie wydarza w kilku kolejnych linijkach kodu.

Nie zmieni to faktu iz przypuszczalnie (czyli w 95% przypadkow) bedzie to leczenie objawow a nie przyczyn.

W wiekszosci sytuacji bledem jest samo odwolywanie sie do algorytu bezposrednio, zamiast schowanie go za warstwa abstracji (IHasher czy tam jak zwal tak zwal) i uwolnienei biednego nastepnego developera ktory ten kod bedzie musial utrzymywac od koniecznosci zwracania uwagi na takie sprawy.

Oczywiscie, mozesz powiedziec ze tu a tam ma to znaczenie i owszem mozesz miec racje, jednak ja, a i wg mojego rozumienia Szymon rowniez, mowie o wiekszosci sytuacji komentarze sa zbedne, wrecz szkodliwe i dlatego powinno sie developerom tluc do glowy ze nie powinni ich uzywac kropka

Krzysztof Koźmic

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 5 listopada 2009 10:20

Dokumentacja XMLowa nie jest w zasadzie wogóle potrzebna klientowi jeśli dostarczasz gotowy produkt w stylu "Program do fakturowania", jeśli jednak produktem jest moduł/dll-ka która ma służyć jako klocek do dalszej układanki, wtedy dokuemntacja XMLowa jest niezbędna.

To czy odwołujesz się do algorytmu bezpośrednio czy przez implementację jakiegoś interfejsu nie ma nic do rzeczy. Przecież w końcu gdzieś implementujesz daną funkcjonalność, czy to pośrednio czy bezpośrednio, wiec tak czy siak wypadało by napisać czemu stosujesz wspomniane SHA256, a nie np SHA512.

Rozumiem, że dyskusja sprowadza się do tego, że kod powinien być samoopisujący się. Zgoda. Ale moim zdaniem jak ktoś gdzieś napisze w kodzie komentarz który będzie pomocny w zrozumieniu wyboru dlaczego ktoś zdecydował się na użycie (niech już będzie to samo) danej funkcji hashującej, to za to po łapach nie powinien dostać. Nie chodzi o opisywanie programu, chodzi o opisywanie pewnych fragmentów pod względem wyboru jednego rozwiązania z grupy innych.

A co z nagłówkami komentującymi kto napisał daną klasę, moduł itp (Headers)? To też jest komentarz.

Darek Tarczynski

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 5 listopada 2009 11:18

"A co z nagłówkami komentującymi kto napisał daną klasę, moduł itp (Headers)?"

To moim zdaniem jeden z nagłupszych wynalazków jakie można zastosować w projekcie. Od tego jest kontrola wersji i funkcjonalnosc BLAME. Z doswiadczenia wiem, ze takie naglowki:

a) nie sa do niczego potrzebne (chyba ze nie uzywa sie wspomnianej kontroli wersji)

b) kłamią

Procent

# re: Kontrowersyjny esej o kodzie czytelnym, część 4: komentarze @ 5 listopada 2009 19:03

Troche za bardzo sie to ciagnie ale niech bedzie.

- "jeśli jednak produktem jest moduł/dll-ka która ma służyć jako klocek do dalszej układanki" wtedy dokumentacja moze byc wynagana przez klienta co nie zmienia faktu iz najczesciej nie jest warta funta klakow, i sam osobiscie stosuje conajmniej cztery frameworki/narzedzia w obecnym projekcie ktore posiadaja szczatkowa badz nieisteniejaca dokumentacje w postaci komentarzy XML, co w zadnym stopniu nie zmniejsza komfortu i wydajnosci mojej pracy z nimi.

- "wypadało by napisać czemu stosujesz wspomniane SHA256, a nie np SHA512", gdzies - bywa ze tak, ale nie w kodzie. Najczesciej w specyfikacji wymagan (ktore sa dyktowane jakimis wymogami licencyjnymi czy paranoja klienta)

- odnosnie headerow Procent w zasadzie powiedzial wszystko

Krzysztof Koźmic

# Czy komentarze to przeżytek? @ 10 grudnia 2009 22:45

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

Cold Fusion

Komentarze anonimowe wyłączone