TeamQuest Blog

Jak pisać sensowne komentarze?

Jak pisać sensowne komentarze?

Marcin Sarna , 26.10.2021 r.

Zgodnie z obowiązującymi poglądami na „czysty” kod najlepiej komentarzy w ogóle nie pisać ale jeśli już – to jak to robić z klasą?

Po co zawracać sobie głowę pisaniem komentarzy do kodu?

W większości przypadków nie jesteś jedyną osobą pracującą nad tym samym projektem. Oznacza to, że inni nie tylko mogą przeczytać Twój kod ale i powinni być go w stanie zrozumieć. Dotyczy to również komentarzy do kodu, które zostawiasz. Nikt nie zrozumie zakomentowanego kodu bez uprzedniego zrozumienia komentarza. Tymczasem deweloperzy często piszą „szybkie” i komentarze „na brudno”. To zła praktyka i lepiej już w ogóle nie pisać komentarzy niż robić to „na odczep”.

W komentarzach chodzi więc o to aby pomóc innym programistom. Komentarz w kodzie opisujący cel funkcji, jej działanie czy jej dane wejściowe i wyjściowe będzie przydatny zwłaszcza dla młodszych programistów. Natomiast często uważa się, że jeśli inny programista nie może zrozumieć celu twojego kodu, patrząc na niego, jest to zły kod i jego zakomentowanie go nie poprawi.

Jak to śpiewał piosenkarz: było ich trzech, w każdym z nich inna krew

Wyróżnia się trzy rodzaje komentarzy:

  • Komentarze dotyczące dokumentacji
  • Ich głównym celem jest szybkie wyjaśnienie przeznaczenia pliku lub komponentu. Zamiast czytać cały kod funkcji czy modułu, aby zrozumieć, co robi, możesz dołączyć komentarz do kodu na górze pliku aby wyjaśnić, co tak w ogóle, generalnie, robi składnik. Takie komentarze nie są zbyt cenione – zanieczyszczają mocno kod i zawierają treść, która raczej powinna znajdować się w wewnętrznej dokumentacji.

  • Komentarze do funkcji
  • To z kolei najbardziej przydatny rodzaj komentarzy, które na dodatek mogą być automatycznie generowane w wielu językach. Opisują one przeznaczenie funkcji, jakich parametrów wejściowych ona oczekuje i jakie dane wyjściowe zwraca. Często wystarczy opisać tylko funkcje publiczne, ponieważ programiści używający Twojego kodu nie będą (nie powinni być) zainteresowani funkcjami prywatnymi.

  • Komentarze logiki
  • Chodzi tu o komentarze w funkcjach, które wyjaśniają bardziej złożone fragmenty. To nic dobrego – obecność takich komentarzy świadczy na ogół o niezbyt dobrym kodzie. Najczęściej jest to oznaka zaciągniętego długu technicznego, wskazującegk na to, że Twój kod jest zbyt złożony. Ponadto komentarze logiczne często zawierają zbyt wiele szczegółowych informacji. A wysoki poziom szczegółowości tworzy chaos i zmniejsza czytelność kodu.

    Napisz, dlaczego coś robisz

    Wielu programistów używa komentarzy, aby opisać, co robi ich kod. To samo w sobie nie jest oczywiście złe ale nie zapomnij przy tym podać, dlaczego utworzyłeś konkretną funkcję lub komponent. Ta informacja nazywana jest kontekstem. Taki kontekst jest niezbędny żeby ktoś kto czyta Twoje wyjaśnienia wiedział dlaczego zapadły takie a nie inne decyzje projektowe.

    Nie zamieszczaj komentarzy do kodu, które używają nazwy funkcji w jej opisie. Jak można się domyślić, taki komentarz nie dodaje żadnej wartości. Kontekst to informacja, której nie da się wywnioskować z nazwy funkcji czy jej zmiennych wejściowych.

    Nie odnoś się do innych dokumentów ani komentarzy

    Nie jest dobrym pomysłem odwoływanie się do innych komentarzy do kodu lub dokumentów wewnętrznych, które wyjaśniają funkcję lub komponent. Komentarze powinny być jasne i „samotłumaczące się” - nikt nie chce tracić czasu na wyszukiwanie innych komentarzy do kodu lub czytanie jakiś PDFów czy dokumentacji online. Jeśli uważasz, że musisz dodać dokument, aby wyjaśnić cel danego fragmentu kodu, to znowu jest to oznaka, że coś jest nie tak nie tyle z komentarzem co Twoim kodem.

Najnowsze oferty pracy:

Polecane wpisy na blogu IT:

Szukasz pracownika IT?

Dostarczymy Ci najlepszych specjalistów z branży IT. Wyślij zapytanie

Wyrażam zgodę TeamQuest Sp. z o.o. na przetwarzanie moich danych osobowych w celu marketingu produktów i usług własnych TeamQuest, w tym na kontaktowanie się ze mną w formie połączenia telefonicznego lub środkami elektronicznymi.
Administratorem podanych przez Ciebie danych osobowych jest TeamQuest Sp. z o.o., z siedzibą w Warszawie (00-814), ul. Miedziana 3a/21, zwana dalej „Administratorem".
Jeśli masz jakiekolwiek pytania odnośnie przetwarzania przez nas Twoich danych, skontaktuj się z naszym Inspektorem Ochrony Danych (IOD). Do Twojej dyspozycji jest pod adresem e-mail: office@teamquest.pl.
W jakim celu i na jakiej podstawie będziemy wykorzystywać Twoje dane? Dowiedz się więcej