4 krótkie rady jak komentować/dokumentować kod

Kilka słów do początkujących i średnio zaawansowanych programistów, o poprawnym komentowaniu swojego kodu. Dlaczego warto to robić, co robić, a czego nie robić. Na te pytania znajdziecie odpowiedzi w niniejszym poście.

Komentarze w kodzie są potrzebne. Niech pierwszy rzuci myszką, kto po 2-miesięcznej przerwie wrócił do kodu bez jakichkolwiek komentarzy i doskonale pamięta która linijka co robi. Zdarza się jednak, że obecność komentarza nie jest zbyt pomocna. Jak więc robić to dobrze?

Za dużo komentarzy gorsze niż brak komentarzy

Częstym problemem początkujących jest komentowanie każdej linijki. Prowadzi to do ogólnego syfu, który potem przeszkadza zamiast pomagać. Nie ma najmniejszego sensu podpisywać linijkę: System.out.println(‚hello world’) komentarzem „wyświetl w konsoli napis hello world”. Być może trochę wyolbrzymiam, jednak informację o tym, co robi dana funkcja można znaleźć w googlach czterema kliknięciami. Szczególnie funkcja, której używamy w kodzie wielokrotnie. W poprawnie napisanym kodzie można dotrzeć do tej informacji jednym kliknięciem za pomocą referencji (o czym później). W skrócie: komentuj to, co twój kod robi, nie to, jak działa.

Pisanie komentarzy wyłącznie po angielsku

Podobnie jak nazwy zmiennych i funkcji, komentarze również powinny być po angielsku, niezależnie od docelowego odbiorcy. Zapomina o tym wielu programistów, nawet w projektach komercyjnych. A potem klient zmienia firmę pracującą nad projektem i jest kwas, bo nikt nie ma pojęcia, jak dana aplikacja działa… i nijak nie idzie tego wywnioskować z komentarzy po włosku. Słabo znasz angielski? Znakomicie, to doskonały sposób na wykonanie pierwszego kroku w celu poprawienia swoich umiejętności.

Zamiast komentować kod tego wymagający, rozważ utworzenie z niego funkcji

Warto zastanowić się czy dany fragment kodu się nie powtarza kilka razy w projekcie i ewentualnie zrobić z niego osobna funkcję. Nawet jeśli nie, pomyśl o potencjalnej rozbudowie aplikacji w przyszłości. Posługując się przykładem z Internetu:

Wiemy co kawałek kodu robi. Nie jest źle, prawda? No właśnie, nie całkiem. Dużo lepszym pomysłem byłoby przerzucenie kodu do osobnej funkcji z intuicyjną nazwą:

A następnie użyć w następujący sposób:

Referencje/Dokumentacja

Większość nowoczesnych języków jak np. Java, PHP, Ruby, C#, czy Python posiada tzw. referencje. Jest to ustandaryzowany sposób opisu metod pod względem realizowanego zadania, przyjmowanych argumentów i zwracanego rezultatu. Różnie jest to nazywane: w PHP jest to PHPDoc, w Javie JavaDoc, w Pythonie Docstrings… nie ma to większego znaczenia. Znaczenie ma cel któremu to służy, a wygląda mniej więcej tak (zależnie od języka):

Wierz mi lub nie, te 3 informacje wystarczają całkowicie do opisania dokładnie zasady działania kodu. Jeśli nie, to prawdopodobnie twój kod jest zbyt długi i powinieneś go rozbić na kilka podfunkcji. Poza informacją dla programisty, do której można się dostać z poziomu środowiska szukając definicji funkcji, jest ona również wykorzystywana do podpowiadania kodu.

 

Do generowania Doców często istnieją gotowe narzędzia, które automatycznie wyciągają maksymalnie co się da, wymagając od programisty dopisania tylko kilku słów.