Jak pisać czysty kod? Poradnik dla junior developera

Pisanie kodu to jedno, ale pisanie czystego, czytelnego kodu, to zupełnie co innego. Jednakże czym właściwie jest „czysty kod”? Stworzyłem ten krótki poradnik pisania czystego kodu dla początkujących, by pomóc wam w zrozumieniu i doskonałym opanowaniu sztuki pisania czystego kodu.

Chris Blakely. Senior Software Engineer w Dawson Andrews. Jego misją jest pomoc młodym i początkującym programistom w ich podróży poprzez tajniki tworzenia dobrego kodu. Uwielbia pisać, tworzyć tutoriale i udzielać się w rozwijaniu projektów open source. Jako doświadczony programista niejednokrotnie prowadził mentoringi i wdrożenia dla młodszych pracowników swoich teamów.


Wyobraź sobie, że czytasz artykuł. Nie ma wstępu, który daje ci ogólne pojęcie, o czym jest tekst. Są nagłówki, każdy z kilkoma akapitami, akapity uporządkowane odpowiednimi kawałkami informacji, zgrupowanymi w takiej kolejności, że tekst „płynie” i dobrze się go czyta.

Teraz wyobraź sobie artykuł bez żadnego wstępu. Są akapity, ale długie i w dezorientującej kolejności. Nie możesz po prostu przejrzeć artykułu, musisz naprawdę zagłębić się w jego treść, aby dowiedzieć się, o czym jest. Pewnie domyślasz się, że czytanie tak sformatowanego tekstu może być frustrujące.

Twój kod powinien być czytelny jak dobry artykuł. Pomyśl o klasach/plikach jak o nagłówkach, a o swoich metodach jak o akapitach. Zdania są instrukcjami w twoim kodzie. Tutaj znajdziesz kilka cech czystego kodu:

  1. Czysty kod jest skupiony. Każda funkcja, każda klasa i moduł powinny robić jedną rzecz i robić ją dobrze.
  2. Powinien być elegancki. Czysty kod powinien być prosty do przeczytania. Czytanie go powinno wręcz wywoływać uśmiech na twojej twarzy. Powinien pozostawić cię z myślą: „Wiem doskonale, co ten kod robi”.
  3. Czysty kod jest zadbany. Ktoś poświęcił swój czas, aby uczynić go prostym i uporządkowanym. Zwrócił należytą uwagę na szczegóły. Zależało mu.
  4. Testy powinny przejść pomyślnie. Wadliwy kod nie jest czysty!

Przechodząc do najważniejszego pytania — jak właściwie pisać czysty kod jako junior developer? Przedstawię moje najważniejsze wskazówki na początek.

Używaj spójnego formatowania i wcięć

Książki byłyby ciężkie do czytania, gdyby odstępy między wierszami były niespójne, rozmiary czcionek różne, a podział wiersza był gdzie popadnie. To samo tyczy się twojego kodu.

Aby uczynić swój kod był przejrzystym i czytelnym, upewnij się, że wcięcia, podziały wierszy i formatowanie są spójne. Oto dobry i zły przykład:

Przykład dobrego formatowania

  • Już na pierwszy rzut oka możesz stwierdzić, że w funkcji znajduje się instrukcja if/else.
  • Nawiasy klamrowe i spójne wcięcia ułatwiają sprawdzenie, gdzie zaczynają się i kończą bloki kodu.
  • Nawiasy klamrowe są spójne zauważ, że nawias otwierający dla function i dla if są w tej samej linii.

Przykład złego formatowania

Rety! Co tu się zadziało!

  • Wcięcie jest zrobione byle gdzie — ciężko powiedzieć, gdzie kończy się funkcja, a gdzie zaczyna blok if/else (tak, jest tam taki blok).
  • Nawiasy są dezorientujące i niespójne.
  • Odstępy między wierszami są niespójne.

To trochę przesadzony przykład, ale dobrze pokazuje korzyści płynące ze stosowania spójnego wcięcia i formatowania. Nie wiem jak dla ciebie, ale dla mnie „dobry” przykład formatowania był o wiele czytelniejszy!

Dobre wiadomości są takie, że jest bardzo dużo wtyczek IDE których możesz użyć do automatycznego formatowania kodu. Alleluja!

Użyj jasnych nazw zmiennych i metod

Na początku mówiłem o tym, jak ważne jest, aby twój kod był łatwy do odczytania. Ważnym tego aspektem jest wybór nazwy (jest to jeden z błędów, które popełniłem, gdy byłem junior developerem). Spójrzmy na przykład dobrego nazewnictwa:

Ten fragment kodu jest dobry z kilku powodów:

  • Funkcje są jasno określone za pomocą dobrze nazwanych argumentów. Gdy developer je odczytuje, jest dla niego jasne, że „jeśli przywoła metodę getStudentName() zestudentId, otrzyma z powrotem imię studenta” – nie muszą nawigować do metodygetStudentName() jeśli nie mają potrzeby.
  • W metodzie getStudentName(), znowu zmienne i nazwy metod są konkretnie nazwane – łatwo zauważyć, że metody wywołują api, otrzymuje obiekt student i zwraca własność name. Prościzna!

Wybieranie dobrych nazw przy pisaniu czystego kodu jako początkujący jest trudniejsze, niż myślisz. W miarę rozwoju aplikacji wykorzystuj następujące konwencje, aby upewnić się, że twój kod jest czytelny:

  • Wybierz konkretny styl nazywania i bądź konsekwentny. Używaj albo camelCase, albo under_scores, ale nigdy obydwu naraz!
  • Nazwij swoje funkcje, metody i zmienne według ich działania lub według tego, czym są. Jeśli twoje metody coś uzyskują, umieść get w nazwie. Jeśli twoja zmienna przechowuje kolor samochodu, nazwij ją przykładowo carColour.

DODATKOWA WSKAZÓWKA — jeśli nie możesz konkretnie nazwać swojej funkcji lub metody, oznacza to, że robi ona zbyt wiele. Śmiało podziel je na mniejsze funkcje! Dla przykładu, jeśli skończysz z funkcją o nazwie updateCarAndSave(), stwórz z niej dwie oddzielne metody, updateCar() i saveCar().

Używaj komentarzy tam, gdzie to konieczne

Mówi się, że „kod powinien być samodokumentujący się”, co w zasadzie oznacza, że twój kod powinien być na tyle czytelny, aby nie było potrzeby stosowania komentarzy. To istotne stwierdzenie i podejrzewam, że ma sens w idealnym świecie. Jednak świat kodowania jest daleki od ideału, dlatego komentarze są czasem konieczne.

Komentarze dokumentacji opisują, co dokładnie robi konkretna funkcja lub klasa. Jeśli piszesz bibliotekę, będzie to użyteczne dla korzystających z niej developerów. Oto przykład z useJSDoc:

Komentarze objaśniające są przeznaczone dla każdego (włączając ciebie w przyszłości), kto będzie potrzebował utrzymać, refaktoryzować bądź rozszerzyć swój kod. Najczęściej komentarzy objaśniających można uniknąć na korzyść „samodokumentującego się kodu”. Oto przykład takiego komentarza:

Tutaj jest kilka komentarzy, których powinieneś spróbować unikać. Nie oferują zbyt dużej wartości, mogą być mylące i zwyczajnie zaśmiecające kod.

Zbędne komentarze niedające wartości:

Mylące komentarze:

Śmieszny lub obraźliwy komentarz:

Pamiętaj o zasadzie DRY (Don’t Repeat Yourself, czyli nie powtarzaj się)

Zasada DRY brzmi:

„Każda cząstka wiedzy musi posiadać pojedynczą, jednoznaczną, autorytatywną reprezentację w systemie.”

ZOBACZ TEŻ:  Od asystentki do frontend programistki. Historia Emilii Kamrowskiej

Na najprostszym poziomie, oznacza to, że powinieneś dążyć do redukcji ilości istniejącego już zduplikowanego kodu. (Zauważ, że użyłem słowa „redukcja”, a nie „eliminacja” w niektórych przypadkach zduplikowany kod to nie koniec świata!)

Zduplikowany kod może być koszmarny do utrzymania i modyfikacji. Spójrzmy na ten przykład:

Wyobraź sobie, że tworzysz dla klienta aplikację do zarządzania zasobami ludzkimi. Aplikacja pozwala adminom dodawać użytkowników wraz z ich rolami do bazy danych przez API. Dostępne są trzy role; pracownika, managera i admina. Spójrzmy na niektóre funkcje, które mogą zaistnieć:

Super! Kod działa i wszystko jest dobrze na świecie. Po chwili nasz klient przychodzi i mówi:

Hej! Chcielibyśmy, aby wyświetlany komunikat o błędzie zawierał zdanie „wystąpił błąd”. Co więcej, żeby być bardziej wkurzający, chcemy zmienić endpoint API z/user na/users. Dzięki!

Zanim więc wskoczymy w wir kodowania, zróbmy krok w tył. Pamiętasz, jak na początku tego artykułu powiedziałem, że „Czysty kod powinien być skupiony”? Aby zrobić jedną rzecz, ale zrobić ją dobrze? To moment, w którym nasz obecny kod napotyka małą przeszkodę. Kod, który sprawia, że API przywołuje i obsługuje błąd, jest powtórzony — co oznacza, że musimy zmienić kod w trzech miejscach, aby spełnić nowe wymagania. To irytujące!

Zapraszamy do dyskusji

Patronujemy

 
 
More Stories
Jak to jest z produktywnością polskich programistów? Śniadanie z Programowaniem #53