Pisanie czytelnego kodu
Czytelny kod (tzw. clean code) jest zrozumiały dla każdego innego programisty, prosty, uporządkowany i w pełni funkcjonalny. Programiści spędzają więcej czasu na czytaniu kodu niż na jego pisaniu, dlatego warto ułatwić sobie i innym to zadanie. Oto kilka dobrych praktyk, które pomogą Ci pisać kod niczym otwartą książkę:
• Stosuj znaczące nazwy - Nadawaj zmiennym, funkcjom i klasom nazwy jasno opisujące ich przeznaczenie. Unikaj skrótów i nazw, które nic nie mówią. Dobrze dobrane nazwy sprawiają, że kod sam w sobie staje się dokumentacją. Gdy patrzysz na nazwę funkcji czy zmiennej, od razu wiesz, za co odpowiada.
• Małe, pojedyncze zadania - Dziel kod na niewielkie, wyspecjalizowane funkcje (najlepiej robiące jedną rzecz). Krótsze funkcje (rzędu kilkunastu-linii) łatwiej zrozumieć, przetestować i ponownie wykorzystać. Taka modularność zwiększa czytelność i zmniejsza ryzyko błędów.
• Konsekwentny styl kodowania - Trzymaj się ustalonych konwencji formatowania i struktury. Ustal w zespole jednolite standardy kodu (wcięcia, nawiasy, nazewnictwo itp.). Spójny styl poprawia czytelność i zmniejsza obciążenie poznawcze programistów, ułatwiając zrozumienie i przeglądanie kodu. Dzięki temu niezależnie od tego, kto pisał dany moduł, wygląda on znajomo dla innych.
• Minimum niezbędnych komentarzy - Staraj się pisać kod tak przejrzysty, by jak najmniej komentarzy było potrzebne. Mówi się, że naprawdę czytelny kod nie wymaga komentarzy, patrząc na niego od razu rozumiesz, co robi. Zamiast komentować zawiły fragment, lepiej go uprościć lub podzielić na mniejsze części. Pamiętaj złotą zasadę: nie komentuj źle napisanego kodu - napisz go lepiej. Lepiej mieć kod precyzyjny i czytelny z małą liczbą komentarzy, niż bałagan, który trzeba tłumaczyć dziesiątkami uwag.
Oczywiście komentarze w kodzie są czasem niezbędne, np. gdy musisz wyjaśnić skomplikowany algorytm, wyrazić założenia biznesowe lub ostrzec o konsekwencjach (np. że dana funkcja nie jest bezpieczna wątkowo). Używaj komentarzy do dodania kontekstu, którego nie da się wyrazić samym kodem. Wielu doświadczonych programistów docenia dobre komentarze i dokumentację. Zdarza się, że podczas przeglądu kodu odrzucą zmianę pozbawioną jakichkolwiek objaśnień. Zadbaj jednak, aby komentarze były aktualne i zgodne z kodem (nie ma nic gorszego niż przeterminowana informacja wprowadzająca w błąd).
Dokumentacja kodu
Pisząc o dokumentacji, mamy na myśli wszystko, co uzupełnia kod o potrzebne informacje. To mogą być:
-Komentarze dokumentujące w kodzie - np. opisy metod, parametrów, przeznaczenia klas. W językach takich jak C# czy Java specjalne komentarze (XML-doc, Javadoc) pozwalają generować automatycznie przejrzyste strony dokumentacji API. Dodatkowo nowoczesne IDE wyświetlają te opisy podczas używania funkcji lub klas, co ułatwia innym korzystanie z Twojego kodu.
-README i instrukcje - pliki Markdown lub Wiki opisujące, jak uruchomić projekt, jak z niego korzystać, zależności, struktura katalogów itp. To pierwsze źródło informacji dla nowych osób w projekcie.
-Dokumentacja projektowa - ważniejsze moduły mogą wymagać szerszego omówienia (np. architektura systemu, diagramy, decyzje projektowe). Takie materiały często przechowuje się w wewnętrznych wiki lub repozytorium dokumentacji.
Kluczem do dobrej dokumentacji jest zwięzłość i aktualność. Pisz tyle, ile trzeba, ani mniej (bo nieznajomy nic nie pojmie), ani więcej (bo nikt nie przeczyta elaboratu). Koncentruj się na dlaczego i jak użyć danego kodu, zamiast przepisywać to, co robi (to widać w kodzie). Dokumentację traktuj jak integralną część projektu: aktualizuj ją przy każdej istotnej zmianie. Poprawnie udokumentowany kod odwdzięczy się mniejszą liczbą pytań od współpracowników i szybszym wprowadzaniem nowych osób do projektu.
Podsumowanie
Czytelność kodu i solidna dokumentacja to nie dodatki, lecz fundamenty profesjonalnego programowania. Inwestując czas w nazewnictwo, strukturę i wyjaśnienia, oszczędzasz sobie (i innym) godzin frustracji w przyszłości. Pamiętaj, że kod piszesz dla przyszłego czytelnika, często nim będziesz Ty sam, za kilka miesięcy. Tworząc zrozumiałe oprogramowanie, budujesz swój wizerunek rzetelnego developera i sprawiasz, że współpraca w zespole przebiega sprawniej.
Z własnego doświadczenia wiem, że opanowanie powyższych praktyk procentuje w każdej pracy programisty. Jeśli chcesz pogłębić wiedzę i nauczyć się dobrych nawyków pod okiem mentora, rozważ dołączenie do jednego z moich szkoleń online. Nie wiesz, który wybrać? Zajrzyj na listę wszystkich szkoleń - znajdziesz tam kursy .NET i nie tylko, które pomogą Ci stać się lepszym programistą.
