Chciałem znaleźć jakieś narzędzie które potwierdzi to co chce napisać ale nie umiem.
TL;DR;
Nie uznaje komentarzy i wy też możecie się ich wyrzec.
/// Dokumentacja
Dlaczego tak mi ona przeszkadza? Często wielkie firmy wymagają aby ich kod był udokumentowany.
Mam tutaj na myśli tą grubą dokumentacje:
Ma tak być ponieważ… W zasadzie chyba nigdy nie usłyszałem dlaczego tak ma być – ciekawa sprawa. Równie ciekawe kto podejmuje taką decyzję, że kod musi być udokumentowany? Osoba która nie zajmuje się programowaniem i nigdy nie zajrzy do kodu? Czy może jest to były techniczny, który teraz jest architektem i też nie zajrzy do kodu, bo układa tylko bloczki w jakimś narzędziu. Nie znam programistów, którzy siedzą cały dzień w IDE i zajmują się programowaniem, a w drugiej połowie dnia z przyjemnością dokumentują kod.
Jak ja widzę taki komentarz lub udokumentowany kod?
O! Kolorowe literki, ciekawe co to? Aha, no tak komentarz. Ciekawe czy jest tam coś ważnego? Aha, no tak klasyk. Geter pobiera, seter ustawia. A to nowość i niespodziewany zwrot akcji. Dziękuje za zmarnowanie mojego czasu. A teraz wrócę do… Co ja miałem zrobić w tej klasie?
Za każdym razem gdy widzę komentarz on kusi mnie swoimi kolorowymi literkami do których nie jestem przyzwyczajony. Być może to tylko mój problem, ale najczęściej dokumentacja w kodzie kojarzy się tak:
// Komentarze
To teraz wracając do tych mniejszych, takie małe drobne wstawki nie powinny przeszkadzać. Cóż dla mnie, nerwusa, też są przeszkodą:
Przykład lekko pod dramatyzowałem, choć i takie się zdarzają. Znalazłem nie najpiękniejszą i nie najkrótszą metodą u siebie i wzbogaciłem ją o komentarze. Zamiast 7 zrobiło się 14 linijek. I teraz znowu nie wiem co mam czytać, czy kod który się kompiluje czy komentarze, które są totalnie bzdurne (jeśli ktoś dokładnie sprawdził).
Po co pisać komentarz, który robi to co robi kod? Czy to nie jest trochę jak z jąkaniem się? (Ja się trochę jąkam więc mogę się nabijać z jąkania). Klasykiem jest:
// returns 1
return 1;
Rozumiem gdyby kod mieli czytać menadżerowie, wtedy można to im opisać, choć wtedy może lepiej obrazkami i wykresami, żeby na pewno zrozumieli.
Jeśli piszesz taki komentarz to zakładasz że ktoś nie zrozumie twojego toku rozumowania i kodu który stworzyłeś. W takim przypadku albo wywal gościa z projektu, bo komentarz i tak tego nie zmieni, nawet jeśli powiesz na głos:
auto jeździ bo w środku jest silnik i on spala paliwo, a efektem spalania jest siła, która napędza tłoki, których siła jest przekazywana dalej poprzez wałki i przekładnie i masę innych części, aż do kół i koła się kręcą, a przez to dzięki sile tarcia samochód się porusza, a to powoduje …. że jedziesz.
Ten cały wywód pójdzie w pi… jeśli gościu nie mówi po polsku. Tak samo z kodem, fajnie że opisałeś po angielsku co robi kod. Co z tego jeśli ktoś nie potrafi programować albo nie zna języka i składni?
Albo
Napisałeś spaghetti i wtedy mogę ci obiecać, że nikt nie zrozumie tego co napisałeś – a po kawie, nawet ty nie ogarniesz swojego kodu. Wtedy na ratunek bierzemy komentarze i piszemy notaki i streszczenia i prozę – nie tędy droga. Może lepiej byłoby zrobić szybki szacher-macher i np. poprzedni kod można zamienić na coś takiego:
Teraz każda linijka w metodzie RegisterCurrentSocialLogin opisuje się sama. Oczywiści że znowu zrobiłem to lekko przesadzone, ale chcę pokazać że nie trzeba komentować kodu. A jeśli tak strasznie cię to kusi, to może weź tę część kodu, wyrzuć do osobnej metody i ulżyj sobie w nazwie metody zamiast w nie potrzebnym komentarzu (@27). Nie ma nic złego w długiej nazwie metody. W zasadzie to dobrze jeśli jest długo, albo bardzo bardzo długo. Bo może zrozumiesz wtedy że dzieje się tam za dużo i może zrozumiesz że warto ją rozdzielić na mniejsze części.
Może w trakcie takiej operacji uda się uprościć kod i komentarze staną się podwójnie zbędne.
Nie mówię, że to co wrzuciłem jako przykład jest jedynym i słusznym rozwiązaniem. Chce pokazać jedno z wielu dostępnych rozwiązań.
Refaktoring
Pamiętacie, kiedy ostatni raz klient powiedział wam żebyście wzięli sobie tydzień wolnego od funkcjonalności i poprawili kod? A pamiętacie, kiedy podczas tego czasu powiedział wam, tylko pamiętajcie żeby poprawić komentarze, żeby po zmianie i naprawach kod był aktualny i rzeczywiście opisywał dokładnie to co wykonuje kompilator?
Kiedy komentarze są ok?
Który komentarz nie powoduje u mnie focha, foszka czy nawet małego ukłucia w serduszku?
Gdy w kodzie dzieje się coś sprzecznego z dokumentacją, bo może jest bug w bibliotece i trzeba zrobić coś inaczej.
Gdy robisz haka i musisz ten kod napisać w taki a nie inny sposób i nie da się tego zrobić czytelniejszym.
Kiedy coś działa a nie powinno, albo nie wiesz czemu, ale boisz się zmienić. Potraktuj komentarz jako wyjątek – musi się stać coś naprawdę strasznego aby go znaleźć
Bardzo proszę nie używaj komentarzy jeśli naprawdę nie musisz. Takie samo podejście mam do regionów.
Mały tip na koniec, wiecie jak poradzić sobie z gościem który musi mieć komentarz? Można tak: Białego na białym nie widać 🙂
Wasze komentarze zawsze mile widziane!
ps.
Dla wszystkich: todo, fix, temporary hack, for later use, etc są odpowiednie narzędzie.
Super wpis!
Słowo komentarza (ha!) ode mnie:
Nasze ulubione IDE pokazuje komentarz ledwie widoczną szarą czcionką. Czyli nawet ono wie, że są mało ważną częścią i sugeruje skupić się na kodzie.
Natomiast jeśli płaciliby mi za każdą linijkę napisaną w plikach .cs to bez wątpienia komentowałbym.
Dzięki 🙂
Ja się zgadzam, że pisanie masła maślanego jest bez sensu. Ale komentarze są jak najbardziej potrzebne. Najbardziej dotyczy to bibliotek. Ile razy ściągam coś z NuGeta i nie ma komentarzy to mnie coś strzela, bo nie można sobie łatwo zobaczyć źródła. Niemniej to samo się tyczy kodu “wewnętrznego”.
Kod, który piszecie nie jest tylko dla klienta i menedżerów. Najważniejszym konsumentem kodu są inni programiści. I mnie się nie chce czytać cudzego kodu. Wolę sensowną nazwę metody i dwa słowa np. o tym jakie wartości przyjmują parametry albo jakiego mogę się spodziewać wyniku (np. “będzie null czy nie?”).
Zamiast komentarzy mogłaby zostać stworzona dokumentacja i tam opisane powinno zostać co i jak działa.
Przyjmowane parametry są w zakresie typu argumentu 😉
Zwracanie nulla nigdy nie jest dobrym rozwiązaniem.
NuGet paczka to troche inna bajka i jest to biblioteka ktora wystawia API ktore musi byc troche lepiej i bardziej udokumentowane.
Dobry post!
Nie wspomniałeś jeszcze o dziennikach programisty – wpisy z datami i tekstem co się zmieniło i dlaczego 🙂
Jednakże brak dokumentacji xml (komentarze) w publicznych bibliotekach jest po prostu rozczarowujący. Po to tworzymy publiczne API aby ktoś z tego mógł skorzystać i w naszym interesie jest to aby było to jak najbardziej wygodne.
W kodzie wewnętrznym jak najbardziej – tutaj wystarczą dobre nazwy metod.
PS: Zwracanie nulla jest akceptowalnym rozwiązaniem w NIEKTÓRYCH sytuacjach np: TryParse, TryGet, FirstOrDefault, TryFind – możliwe wystąpienie nullowej wartości też można dobrze opisać w nazwie metody.
Dzięki 🙂
Kiedyś musieliśmy trzymać ostatnie 10 zmian w headerze plików, stare mroczne czasy c++.
Jeśli chodzi o publiczne biblioteki to mogę przymknąć na to oko, ale to po starej znajomości.
Z tym nulem to łapiecie mnie za wyjątkowe sytuacje 🙂
Jak dla mnie podejście z nazwami typu “CreateAndAssignNewSocialLoginForApplicationUser” zupełnie nie ma sensu. Właśnie w takich przypadkach powinny być wykorzystywane komentarze. Używanie nazw powyżej 30 znaków jest zwyczajną obfuskacją i niezrozumieniem zasady SRP (Single responsibility principle). Dodatkowo dobrze zastanowiłbym się nad tworzeniem metod z takich powodów, jeżeli nie wydzielają one wspólnej logiki, która jest w miarę możliwości niezależna i możliwa do użycia w wielu miejsach to można sobie szybko zrobić n warstw abstrakcji, które są trudne w utrzymaniu oraz cała architektura nie jest zbyt przejrzysta ale to jeszcze kwestia jakie rozwiązanie się wdraża i jakie umiejętności posiada. Co do samych komentarzy mile widziane są przynajmniej przeze mnie komentarze w miejscach logiki biznesowej, która często dla programista wyłącznie pewnej części całego systemu nie musi być zrozumiała. Dokumentacja jest dobrą rzeczą jak ma się czas ją przygotować i aktualizować, lecz ja tam wole móc na szybko sprawdzić opis metod w Intellisense zamiast wertować po 200 stron i więcej, a przy okazji potrzebie opisu najważniejszych części systemu można zwyczajnie wygenerować takowy o ile opisy są w miarę sensowne. Tego z rzucającym się w oczy kolorem komentarzy nie rozumiem zupełnie. Masz wspaniałe narzędzie programistyczne wyposażone w masę uprzyjemniaczy pisania kodu i szerokie możliwości customizacji, a nie potrafisz dostosować takiego banału do swoich potrzeb? Fakt jest to trochę zaniedbany temat i wielu nawet doświadczonych programistów używając IDE korzysta z domyślnych ustawień, nie zna żadnych skrótów i ogólnie wiele by nie zmieniło się gdyby mieli notatnik z opcją kompilacji i debugowania, lecz naprawdę warto poznać własne IDE i dostosować. W końcu ktoś na podstawie potrzeb programistów te IDE przygotował, więc warto to sprawdzić.
@Koko, SRP polega właśnie na tym, że metod i klas nie wydziela się wtedy, gdy są potrzebne w wielu miejscach, ale wtedy, gdy robią jedną rzecz, którą jesteśmy w stanie nazwać.
Koko dzięki za komentarz,
1. Trochę nie rozumiem co jest złego w nazwach metod które są długie.
2. Rzeczywiście jeśli jest AND w nazwie czegokolwiek, można podejrzewać to miejsce o łamanie SRP
3. Komentowanie algorytmów czy logiki biznesowej w kodzie: kiedyś tak próbowałem, ale zmieniłem to na rzecz dłuższym nazw metod, które w zasadzie robiły to co było w komentarzu.
4. Kolorowe literki biorą się z domyślnych tematów które są VS. Na jasnym temacie komentarze są na szczęście lekko wyszarzone. Jednak jest to kolor, którego nie rozpoznaje automatycznie, ponieważ unikam komentarzy – może dlatego napisałem, że jest kolorowy. Nie wiem jaki rodzaj dopasowania mogę zrobić żeby było lepiej, niż białe-na-białym.
5. Jeśli masz jakieś ciekawe tips’n’tricks dotyczące VS to chętnie przyjmę.
6. Będę super wdzięczny za przykład tego jak Twoim zdaniem powinno to wyglądać. Zawsze powtarzam, że moje podejście nie musi być tym jedynym i chętnie poznam inne rozwiązania, które może wpłyną na to jak będę pisać kod.
To ja tez mam pytanie:
Testuje obecnie takie rozwiązanie, że nie używam komentarzy tylko jeśli jest coś zawiłego to zamiast linijki z komentarzem daje linijkę z wpisem do logów.
Pomysł był taki, żeby dzięki temu zyskać podwójnie i informację dla innego programisty, który będzie to czytał i dla kogoś kto będzie czytał logi.
Stosuje to od roku i na razie jest ok. nikt nie narzeka. Pytanie czy z Twojego Waszego doświadczenia takie podejście jest ok?
Nie rozumiem trochę, w komentarzu dajesz linka do logów które są zapisane gdzieś na dysku? A gdzie są logi archiwizowane?
Czego dotyczy komentarz? Coś na zasadzie:
// zrobiłem taki hack, bo taka była sytuacja, sprawdź logi xyz#0123
Jeśli tak i tego nie ma dużo i to jest rzeczywiście sporadyczna sprawa to wszystko tak naprawdę zależy od ludzi w projekcie. Tak naprawdę do wszystkiego można się przyzwyczaić. Jeśli to robi robotę dla Ciebie i Twojego zespołu to jasne. Gdybym był w projekcie może bym narzekał na początku 😉
Przypominam, że nie jestem wyrocznią.