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
- Komentarze do funkcji
- Komentarze logiki
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.
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.
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.
