Komentowanie kodu może bardzo pomóc w jego czytaniu i rozumieniu, zaraz wyjaśnię dlaczego tak uważam. Natomiast już na początku chcę zamieścić mały disclaimer – praktyka ta nie jest dla osób, które nie przywiązują estetycznej wagi do pisanego kodu, nie jest też dla osób którzy nie dbają o jakość kodu oraz nie jest dla osób nie pilnujących co gdzie piszą. Oczywiście, nie jest też dla osób zwyczajnie “leniwych”, ale mam tu na myśli osoby które mają tak jako stan domyślny, bo zwyczajnie każdemu czasem się czegoś nie chce i nie ma w tym nic złego, o ile to kontrolujemy.
Jeśli nie należysz do osób z wypisanymi cechami – ten post jest dla Ciebie.

Co daje komentowanie kodu?

  • Szybsze zapoznawanie się z kodem – zamiast czytać skomplikowany kod, możemy przeczytać kilka linijek komentarzy, które jasno i wprost tłumaczą krok po kroku co robi np. dana funkcja. W taki sposób, ktoś kto nie pisał tego kodu, może w łatwy sposób zrozumieć jak działa, w jaki sposób, i dlaczego akurat tak, a także może lepiej wyłapać potencjalne błędy rozumowania.
  • Darmowa dokumentacja kodu – często zadanie pisania dokumentacji jest żmudne i nudne (podobnie jak pisanie testów, ale to oddzielna kwestia), więc sam fakt, że dbając o kod od początku i pisanie na bierząco komentarzy dostarcza nam darmową wygenerowaną dokumentację na temat całego kodu jest dosyć satysfakcjonujący. Przykładowo C# jest w stanie samemu wygenerować całą dokumentację na podstawie komentarzy typu <summary> które są nad każdą funkcją, propertisem, klasą itd.
  • Zrozumienie intencji kodu – dlaczego został napisany w taki a nie inny sposób? Dlaczego został zastosowany tutaj Sposób#1 zamiast Sposob#2 ? Odpowiedzi na te i inne pytania niosą właśnie komentarze

Znamy już najbardziej istotne zalety, z wad pasuje w sumie to wymienić, że trochę nam się bardziej klawiatura zużyje, więc jeśli komuś się ona rozwala, albo brakuje kilku klawiszy, to ma wymówkę by komentów nie pisać 🙂
Ale komentarze takie “byleby były” nie są dobre. Powinny one być pisane poprawnie, by właśnie każdemu pomagały, zamiast przeszkadzać.

Jak pisać dobre komentarze?

  • Przede wszystkim, nie ma sensu przepisywać kodu, więc zamiast tego powinniśmy pisać co dany kod oznacza, co dany kod robi, lub dlaczego dany kod jest napisany tak a nie inaczej.
  • Priorytet mają oczywiście funkcje/propertisy/klasy itp., to dla nich komentarze są najważniejsze, aby np. wiedzieć którą funkcję użyć bez potrzeby zaglądania w jej szczegółową implementację.
  • Bardzo przydatne okazuje się pisanie o różnych przypadkach danych, przykładowo jeśli funkcja przyjmuje jakąś flagę (boola), to warto zaznaczyć co się stanie przy false, a co przy true. Polecam takie rzeczy poprzedzać jakimś prefixem dla czytelności, ja używam // NOTE: Treść
  • Komentarze typu “zrób coś jak będzie chwila czasu” polecam poprzedzić // TODO: Treść – tym bardziej, że we wszystkich IDE jest opcja wyszukania wszystkich takich właśnie ToDos i dzięki temu można je fixnąć, a nie zostaną w kodzie na wieki.
  • Powinny one być po angielsku. Koniec kropka. Akurat ten temat nie może podlegać dyskusji. Myślę, że większość osób się zgodzi. Naturalnym językiem kodu (komentarze też poniekąd należą do kodu) jest właśnie angielski.

Przykłady z życia wzięte

Przykład z kodu Microsoftu, ich kod czyta miliony ludzi, dbają o jego jakość, i jak widać stosują mnóstwo komentarzy. Dzięki temu w bardzo łatwy sposób możemy zrozumieć co dana funkcja robi oraz kontekst jej użycia.
Tutaj mamy przykład kodu z aplikacji. Tak naprawdę, całą funkcję można zrozumieć czytając tylko “zielone” linijki. Mamy wytłumaczenie co robi funkcja, mamy opisane co się pokolei dzieje, mamy wytłumaczone co się stanie po returnie z funkcji (bez komentarza nie byłoby to oczywiste), mamy wszystko.

Przykładów można by mnożyć w nieskończoność. W sumie to dobrym pomysłem będzie od dzisiaj zbieranie wszystkich fajnych sytuacji związanych z komentarzami, czy to napisanymi wyjątkowo dobrze, czy wręcz przeciwnie, może powstanie z tego w przyszłości kolejny post na ten temat.

Mam nadzieję, że zachęciłem Cię do poprawnej dokumentacji Twojego kodu. Przyznaję, że ten temat jest trochę kontrowersyjny, szczególnie, że parę lat temu programowanie było dla “elit” i zwykli ludzie nie rozumieli kodu, a programiści siedzieli w jednych firmach po kilkanaście lat. Teraz czasy się zmieniły, dokumentacja kodu jest bardzo ważna, programowanie się rozpowszechniło i wymiana ludzi w teamie jest bardzo częsta. Często jak obecnie rozmawiam z przeciwnikami komentarzy, to tak naprawdę sprowadza się to do dwóch sytuacji – albo ktoś się naczytał starych książek które uważa za świętość typu “Czysty Kod”, albo ktoś jest po prostu leniwy i szuka wymówek by tych komentarzy nie pisać. Wad komentarzy jest bardzo mało w porównaniu do zalet, więc pisanie ich powinno być normą, co zresztą większość dużych firm typu Microsoft promuje.

Niech kod (udokumentowany) będzie z Tobą!


Patryk Mikulski

Programowaniem zajmuje się od 4 lat i jest to moja pasja. Jestem autorem wszystkiego co związane jest z ProtonSoftware.NET. Specjalizuję się w platformie .NET z językiem C# na czele. Pracuję zarówno na etacie, jak i zajmuję się własnymi aplikacjami. Najlepiej czuję się w roli team leadera. Preferuję pełne skupienie na praktyce i efektach pracy - teoria jest dobra tylko w teorii.

0 Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

en_GBEnglish
en_GBEnglish