Komentarze są zbędne poza
- javadoc dla API, z którego będzie korzystał klient,
- wyjaśnienia haków.
Programiści od których to usłyszałem zarazili mnie wcześniej programowaniem w parach, testami jednostkowymi, programowaniem zorientowanym na odpowiedzialność i kilkoma innymi praktycznymi technikami.
Parę(naście) lat dłużej ode mnie programują więc daruję im, że szybciej się zarazili dobrymi praktykami niż ja. Ale komentarzy nie podaruję.
"When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous."
Teza o braku komentarzy jest wydaje się być żywcem wyjęta z ewangelisty M. Fowlera (ja znalazłem w
Refaktoryzacja ...).
Podobne słowa można spotkać w kontekście stosowania testów jednostkowych. Zresztą
jest stosowana.
Mam swoje (naiwne?) obawy co do takiego podejścia.
W obu przypadkach mam wrażanie że nie czuję słodkiego zapachu. Całkowita rezygnacja z pisania komentarzy (dokumentujących) to podejście bardzo radykalne. Zresztą mam wrażenie że jest to pójście za ciosem myśli Fowlera, ale pójście za ciosem bez gardy i niezbyt przemyślane.
Oto garść na szybko wymyślonych argumentów:
Miło jest jak autouzupełnianie pokazuje Ci opis API i nie musisz przy
każdej metodzie szukać testów, które pisałeś n-czasu temu albo ...
... które pisał kolega
... w drugim końcu polski
... który odszedł z firmy
... nie do końca w miłej atmosferze
... a ty masz tylko skompilowaną bibliotekę bez źródeł.
Nierealne? Mi się zdarzyło.
Do tego ta cała masa kodu, będącego efektem ciągłych zmian wymagań i takiej presji terminów że się biega z pustymi taczkami bo nie ma czasu ich załadować ...
... napisana przez programistę C
... z nawykiem nieustannej optymalizacji kodu na poziomie bitów
... sama aplikacja w Java
... albo w języku jednokrotnego zapisu typu Perl.
Elementy te czasami się łączą w dziwny sposób.
A jeśli testy jednostkowe testują jedynie warunki brzegowe bo zabrakło czasu na typowe :)
Może to kompleks z traumatycznych przeżyć w przeszłości ale jestem wielkim fanem komentarzy. Zamierzam troskliwie dbać by nie wyrosnąć z tego kompleksu.
Dobrze myślę o programiście, który zostawia komentarz w kodzie nawet, gdy nie zostawia eleganckiego kodu ... nawet jeśli nie zostawia wcale kodu :D ech nawet jeśli zostawia rewelacyjnej jakości kod ;P
Komentarze to nie tylko moja obsesja.
Ta wypowiedź M. Fowler'a zawiera jednocześnie definicję i uzasadnienie dla komentarzy:
A comment is a good place to say why you did something. This kind of information helps future modifiers, especially forgetful ones.
Fowler przestrzega przed używaniem komentarzy jako wymówki usprawiedliwiającej pisanie nieczytelnego kodu ...
The reason we mention comments here is that comments often are used as a deodorant. It's surprising how often you look at thickly commented code and notice that the comments are there because the code is bad.
... podpowiada, że komentarz może sugerować, iż warto wydzielić komentowany kod do osobnej metody:
whenever we feel the need to comment something, we write a method instead. Such a method contains the code that was commented but is named after the intention of the code rather than how it does it.
... albo zastąpienia go asercją:
Sometimes the assumptions are stated with a comment. A better technique is to make the assumption explicit by writing an assertion.
Komentarze można pominąć w pewnych częstych wypadkach
we often find that the comments are superfluous.
... ale nie zawsze:
Don't worry, we aren't saying that people shouldn't write comments. In our olfactory analogy, comments aren't a bad smell; indeed they are a sweet smell. The reason we mention comments here is that comments often are used as a deodorant. It's surprising how often you look at thickly commented code and notice that the comments are there because the code is bad.
Po co rozwijać myśl uznanego autorytetu w kierunku przed którym on sam przestrzega?
3 komentarze:
Pozwolę sobie na komentarz do komentarzy, niejako sprowokowany przeinaczeniem mojej opinii:)
Prostuję więc.
a. JavaDoc, #owy xml itp są bardzo OK dla typów (klas i interfejsów) i metod przez nich wystawianych
b. Praktycznie w całości zgadzam się z MF. Fragment, który przytaczasz sugerując, jakoby rzeczony był za komentarzami, jest bardzo hmmm... nijaki:) MF jako guru;) bardzo często zachowuje się niezwykle dyplomatycznie i tak też jest pewnie i w tym przypadku.
Równie dobrze ten fragment można rozumieć tak:
"Jeśli kod jest jasny, nie ma potrzeby pisania komentarzy"
Komentarz piszę wtedy, kiedy nie ma innego sposobu na poinformowanie czytającego, dlaczego tak a nie inaczej zachowałem się w tym miejscu.
c. "Hak" (skąd systemowy?) to miejsce, w którym robię coś co nie jest oczywiste, nawet więcej - jest dziwne i nieoczekiwane, przykładem może być asercja na jedynej wartości powodującej błąd w metodzie, którą wywołuję i do kodu której nie mam dostępu. Wydaje mi się, że definicja tego sformułowania jest potrzebna.
Nb fragment "whenever we feel the need to comment something" można odnaleźć w "Code Complete" w nieco ostrzejszej formie ćwiczenia którego elementem jest... zakaz pisania komentarzy. (Mam nadzieję że nie ściemniam, dawno czytałem.)
Z pokrewnej beczki; spotkałem się kiedyś z powiedzeniem:
"Pisz kod tak, jakby ten, który go po tobie przejmie, był maniakalnym terrorystą" :)
TNXE6 za komentarz.
ad a)
Jest spora przestrzeń między interfejsem wystawianym a wszystkim poza prywatnymi polami (i metodami) - zob wypowiedź Kazimierza Pogody z linku "Komentarze to nie tylko moja obsesja" już lubię tego gościa :D
ad b)
"comments aren't a bad smell; indeed they are a sweet smell" - dla mnie to nie jest nijakie
a co do "kiedy nie ma innego sposobu" hmmm czasem (zbyt często) z dobrze napisanego kodu zostają tylko komentarze a jak ich nie ma ...
ad c)
Nie przymierzam się do czytania Code Complete. Wolę poświęcić czas np na sen po dłubaniu w kodzie tym bardziej że zdarzają mi się takie kwiatki jak "hak systemowy" (poprawione). To ćwiczenie w CC to CWICZENIE a nie zalecenie - "what's your point"?
"Zbyt często z dobrze napisanego kodu(...)" Piotrze. Co innego pragmatyzm i liczenie się z awaryjnymi sytuacjami które z definicji nie powinny mieć miejsca, a co innego traktowanie takich sytuacji jako coś co powinno kształtować nawyki nasze - czyli programistów idealnych.
Zresztą tym przykładem strzeliłeś sobie właśnie bramkę. W takich awaryjnych sytuacjach komentarze zostają - bo nie ma czasu ich zmieniać - a kod się zmienia.
Praktyka pokazuje, że duplikacja informacji to zło. Wolę nie mieć komentarza w ogóle, niż mieć komentarz mylący.
Zresztą zobaczymy za 10 lat;)
Howgh!
Prześlij komentarz