Dawno temu chciałem napisać artykuł — ależ to słowo jest popularne na moim blogu — na temat pisania dobrych komentarzy. Podczas pracy na kodem wiele razy spotkałem się jak moi współpracownicy pisali komentarz, który nic nie wnosił. Jak ustrzec się przed takimi komentarzami? Garść mojego doświadczenia oraz wielki skrót rozdziału 4. z książki — a raczej podręcznika każdego developera — “Clean Code” autorstwa Roberta C. Martina.
Clean Code — kilka słów od wujka Martina
Cytaty pochodzą z książki pt. “Czysty kod. Podręcznik dobrego programisty” wydawnictwa Helion.
-
“Za każdym razem, gdy piszemy komentarz, powinniśmy poczuć smak porażki.”
Moja opinia: Zgadzam się. Często, gdy widzę komentarz, to znaczy, że ktoś napisał taki kod, który wg autora nie jest zrozumiały — dlatego, aby pomóc sobie i innym czytającym, autor kodu napisał komentarz.
-
“[kod]… jest jedynym źródłem naprawdę dokładnych informacji”
Moja opinia: Dokumentacja (czyli kod), nigdy nie będzie, z uwagi na potrzebę zapewnienia synchronizacji z kodem, co niesie ze sobą kolejne zadanie dla programisty.
-
“Wszystkie komentarze, które wymuszają zaglądanie do innych modułów, w celu ich zrozumienia, nie są warte bitów, które zajmują.”
Moja opinia: Ile to razy miałem problem z odczytem komentarza. Otwierałem kolejne pliki, aby lepiej zrozumieć jego sens.
-
“Wymaganie, aby każda funkcja posiadała Javadoc lub aby każda zmienna posiadała komentarz jest po prostu głupie.”
Moja opinia: Zgadzam się i dlatego też często wyłączamy opcje w ESLint sprawdzającą, czy przed funkcję mam napisanego JSDoca. Bez sensu pisać komentarz do każdej funkcji.
-
“Nie używaj komentarzy, jeżeli można użyć funkcji lub zmiennej”
Moja opinia: Trudno będzie znaleźć kontrargument. Jako developerzy czytamy kod. Jeśli nazwy funkcji i zmiennych odzwierciedlają to, co robią oraz przechowują, to w takich przypadkach rzadko pojawią się komentarze.
-
“Zadaniem komentarza jest wyjaśnienie kodu, który sam się nie objaśnia”
Moja opinia: Dlatego też lepiej jest napisać dobry kod. Nie jestem zwolennikiem używania tzw. “magic numbers” oraz “magic strings”. Zawszę tworzę stałą, która będzie przechowywała daną wartość. Każda stała ma swoją nazwę, która powinna uzasadnić istnienie danej wartości.
Moja najważniejsza porada
Jak już piszesz komentarz — zrób to właściwie. Dlatego, jeśli miałbym udzielić tylko jednej porady to unikaj powtarzających komentarzy.
Zły przykład komentarza, który opisuje jak kod działa:
// Stworzenie zmiennej, która przechowuje opóźnienie
const LOAD_DELAY = 500;
Dobry przykład komentarza, który wyjaśnia:
- dlaczego taki kod został stworzony?
- komu się przydaje?
// Sztuczne opóźnienie (w milisekundach),
// aby zasymulować uruchamianie systemu.
// Zapewnienie lepszego user experience.
const LOAD_DELAY = 500;
•
Jestem bardzo zadowolony z lektury rozdziału 4. książki “Clean Code” - równo 20 stron. Książka opisuje doświadczenie developerów, którzy “zjedli zęby” na wytwarzaniu oprogramowania. Może być ona czytana “na wyrywki”, czyli nie trzeba jej czytać od deski do deski.
Książka ląduje do sekcji “Polecane książki”.