Clean Code

1. Pisz czysty kod, który jest czytelny i łatwy do utrzymania

Jedyny prawdziwy miernik jakości kodu: WTFs/minuta

Czytelność jest najważniejsza. Czysty kod powinien być łatwo zrozumiały dla innych programistów. Powinien być prosty, elegancki i wolny od zbędnych elementów. Staraj się pisać kod, który jasno wyraża swoje intencje bez potrzeby rozbudowanych komentarzy. Używaj znaczących nazw zmiennych i funkcji, utrzymuj funkcje małe i skoncentrowane oraz organizuj kod logicznie.

Łatwość utrzymania umożliwia ewolucję. Kod, który jest trudny do zmiany, staje się obciążeniem. Projektuj swój kod tak, aby był elastyczny i modułowy, aby mógł dostosować się do zmieniających się wymagań. Stosuj zasady takie jak DRY (Don't Repeat Yourself) i SOLID, aby tworzyć luźno powiązane, wysoko spójne systemy. Refaktoryzuj bezlitośnie, aby poprawić strukturę kodu bez zmiany jego zachowania.

Czysty kod się opłaca. Chociaż pisanie czystego kodu wymaga większego wysiłku na początku, oszczędza to znaczną ilość czasu i problemów w dłuższej perspektywie. Czysty kod jest łatwiejszy do debugowania, rozszerzania i utrzymania. Umożliwia programistom bardziej efektywną pracę i zmniejsza ryzyko wprowadzenia błędów podczas zmian. Uczyń czysty kod podstawowym elementem swojej praktyki programistycznej.

2. Stosuj znaczące konwencje nazewnicze

Nazwa zmiennej, funkcji lub klasy powinna odpowiadać na wszystkie ważne pytania. Powinna mówić, dlaczego istnieje, co robi i jak jest używana.

Używaj nazw ujawniających intencje. Wybieraj nazwy, które jasno przekazują cel i zachowanie zmiennych, funkcji i klas. Unikaj nazw jednoliterowych lub kryptograficznych skrótów. Używaj nazw, które można łatwo wymówić i wyszukać. Na przykład:

• Złe: d (czas upływu w dniach)
• Dobre: elapsedTimeInDays

Bądź konsekwentny i precyzyjny. Stosuj spójne konwencje nazewnicze w całym kodzie. Bądź precyzyjny, aby uniknąć niejednoznaczności - na przykład, używaj znaczących rozróżnień, takich jak getActiveAccounts() i getActiveAccountInfo(). Unikaj kodowania lub prefiksów, które dodają szum bez wartości. Nazwy klas powinny być rzeczownikami, a nazwy metod czasownikami.

Długość nazwy powinna odpowiadać zakresowi. Używaj dłuższych, bardziej opisowych nazw dla zmiennych i funkcji o większym zakresie. Krótkie nazwy są akceptowalne dla małych, lokalnych zakresów. Długość nazwy powinna być proporcjonalna do zakresu jej użycia. Optymalizuj pod kątem czytelności i zrozumienia w kontekście, w którym nazwa jest używana.

3. Utrzymuj funkcje małe i skoncentrowane

Funkcje powinny robić jedną rzecz. Powinny robić to dobrze. Powinny robić tylko to.

Małe jest piękne. Funkcje powinny być małe - zazwyczaj 5-10 linii długości. Powinny mieścić się na jednym ekranie i być natychmiast zrozumiałe. Wyodrębniaj kod do dobrze nazwanych funkcji pomocniczych, zamiast pisać długie, skomplikowane funkcje. Małe funkcje są łatwiejsze do zrozumienia, testowania i utrzymania.

Rób jedną rzecz dobrze. Każda funkcja powinna mieć jeden, jasny cel. Jeśli funkcja robi wiele rzeczy, wyodrębnij je do oddzielnych funkcji. Oznaki, że funkcja robi zbyt wiele, to:

• Wiele poziomów abstrakcji
• Wiele sekcji lub bloków kodu
• Liczne parametry

Utrzymuj jeden poziom abstrakcji. Instrukcje w funkcji powinny być na tym samym poziomie abstrakcji. Nie mieszaj logiki wysokiego poziomu z detalami niskiego poziomu. Wyodrębniaj operacje niskiego poziomu do oddzielnych funkcji. To poprawia czytelność, utrzymując funkcje skoncentrowane i koncepcyjnie proste.

4. Praktykuj właściwe formatowanie i organizację

Formatowanie kodu to komunikacja, a komunikacja jest pierwszym zadaniem profesjonalnego programisty.

Spójne formatowanie ma znaczenie. Używaj spójnego wcięcia, łamania linii i odstępów w całym kodzie. To poprawia czytelność i zmniejsza obciążenie poznawcze. Uzgodnij standardy formatowania z zespołem i używaj narzędzi automatyzujących ich egzekwowanie. Kluczowe wytyczne dotyczące formatowania to:

• Właściwe wcięcia
• Spójne umieszczanie nawiasów
• Logiczne łamanie linii
• Odpowiednie odstępy

Organizuj kod logicznie. Grupuj powiązany kod razem i oddzielaj niepowiązany kod. Używaj pustych linii, aby tworzyć "akapitowe" przerwy między logicznymi sekcjami. Umieszczaj powiązane funkcje blisko siebie. Utrzymuj pliki skoncentrowane na jednym koncepcie lub komponencie. Rozbijaj duże pliki na mniejsze, bardziej skoncentrowane, gdy jest to odpowiednie.

Stosuj standardowe konwencje. Przestrzegaj standardowych konwencji dla swojego języka i społeczności. To sprawia, że twój kod jest bardziej znajomy i dostępny dla innych programistów. Na przykład, w Javie:

• Nazwy klas używają PascalCase
• Nazwy metod używają camelCase
• Stałe używają ALL_CAPS

5. Zarządzaj zależnościami i unikaj duplikacji

Duplikacja może być źródłem wszelkiego zła w oprogramowaniu.

Eliminuj duplikację. Zduplikowany kod to stracona szansa na abstrakcję. Gdy widzisz duplikację, wyodrębnij wspólny kod do funkcji lub klasy do ponownego użycia. To poprawia łatwość utrzymania, centralizując logikę i zmniejszając ryzyko niespójnych zmian. Typy duplikacji, na które należy zwracać uwagę:

• Identyczne bloki kodu
• Podobne algorytmy z niewielkimi wariacjami
• Powtarzające się łańcuchy switch/case lub if/else

Zarządzaj zależnościami ostrożnie. Minimalizuj zależności między modułami, aby zmniejszyć sprzężenie. Używaj wstrzykiwania zależności i odwrócenia kontroli, aby uczynić kod bardziej modułowym i testowalnym. Stosuj zasadę odwrócenia zależności - polegaj na abstrakcjach, a nie na konkretnych implementacjach. To sprawia, że twój kod jest bardziej elastyczny i łatwiejszy do zmiany.

Stosuj zasadę najmniejszej wiedzy. Moduł nie powinien znać wnętrza obiektów, którymi manipuluje. To zmniejsza sprzężenie między modułami. Na przykład, stosuj Prawo Demeter - metoda powinna wywoływać tylko metody na:

• Własnym obiekcie
• Obiektach przekazanych jako parametry
• Obiektach, które tworzy
• Swoich bezpośrednich komponentach

6. Obsługuj błędy elegancko

Obsługa błędów jest ważna, ale jeśli zaciemnia logikę, jest błędna.

Używaj wyjątków zamiast kodów błędów. Wyjątki są czystsze i nie zaśmiecają głównej logiki twojego kodu. Pozwalają na oddzielenie obsługi błędów od ścieżki sukcesu. Podczas używania wyjątków:

• Twórz informacyjne komunikaty o błędach
• Dostarczaj kontekst z wyjątkami
• Definiuj klasy wyjątków na podstawie potrzeb wywołującego

Nie zwracaj null. Zwracanie null prowadzi do wyjątków wskaźnika null i zaśmieca kod sprawdzeniami null. Zamiast tego:

• Zwracaj puste kolekcje zamiast null dla list
• Używaj wzorca Null Object
• Używaj Optional w Javie lub Maybe w językach funkcyjnych

Pisz instrukcje try-catch-finally najpierw. Zacznij od try-catch-finally, pisząc kod, który może rzucać wyjątki. To pomaga zdefiniować zakres i oczekiwania dla wywołującego kodu. Zapewnia, że zasoby są odpowiednio zarządzane i zwalniane, nawet w scenariuszach błędów.

7. Pisz dokładne testy jednostkowe

Kod testowy jest równie ważny jak kod produkcyjny.

Przestrzegaj trzech zasad TDD. Test-Driven Development (TDD) poprawia jakość i projekt kodu:

1. Napisz nieudany test przed napisaniem jakiegokolwiek kodu produkcyjnego
2. Napisz tylko tyle testu, aby wykazać błąd
3. Napisz tylko tyle kodu produkcyjnego, aby test przeszedł

Utrzymuj testy czyste i łatwe do utrzymania. Stosuj te same standardy jakości kodu do testów, co do kodu produkcyjnego. Regularnie refaktoryzuj i poprawiaj kod testowy. Dobrze zorganizowane testy służą jako dokumentacja i umożliwiają bezpieczne refaktoryzowanie kodu produkcyjnego.

Dąż do kompleksowego pokrycia testami. Pisz testy, które obejmują przypadki brzegowe, warunki graniczne i scenariusze błędów - nie tylko ścieżkę sukcesu. Używaj narzędzi do pokrycia kodu, aby zidentyfikować luki w pokryciu testami. Pamiętaj, że 100% pokrycia nie gwarantuje braku błędów, ale daje pewność przy refaktoryzacji i zmianach.

8. Refaktoryzuj kod ciągle

Zostaw obozowisko czystsze, niż je zastałeś.

Refaktoryzuj oportunistycznie. Poprawiaj strukturę kodu za każdym razem, gdy pracujesz nad jego fragmentem. Stosuj zasadę Boy Scout: zostaw kod lepszy, niż go zastałeś. Małe, stopniowe ulepszenia sumują się z czasem i zapobiegają gniciu kodu. Typowe techniki refaktoryzacji to:

• Wyodrębnianie metod lub klas
• Zmiana nazw dla jasności
• Upraszczanie złożonych warunków
• Usuwanie duplikacji

Refaktoryzuj bezpiecznie z testami. Zawsze miej solidny zestaw testów przed refaktoryzacją. Dokonuj małych, stopniowych zmian i często uruchamiaj testy. To daje pewność, że twoje zmiany nie psują istniejącej funkcjonalności. Używaj narzędzi do automatycznej refaktoryzacji, gdy są dostępne, aby zmniejszyć ryzyko wprowadzenia błędów.

Równoważ refaktoryzację z dostarczaniem wartości. Chociaż ciągła refaktoryzacja jest ważna, nie pozwól, aby paraliżowała postęp. Dąż do "wystarczająco dobrego" zamiast perfekcji. Skupiaj wysiłki refaktoryzacyjne na najbardziej problematycznych lub często zmienianych obszarach kodu. Komunikuj wartość refaktoryzacji interesariuszom, aby zapewnić wsparcie dla ciągłego doskonalenia kodu.

9. Stosuj zasady programowania obiektowego i funkcyjnego

Obiekty ukrywają swoje dane za abstrakcjami i udostępniają funkcje, które operują na tych danych. Struktury danych udostępniają swoje dane i nie mają znaczących funkcji.

Stosuj zasady programowania obiektowego mądrze. Stosuj zasady takie jak enkapsulacja, dziedziczenie i polimorfizm, aby tworzyć elastyczne, modułowe projekty. Przestrzegaj zasad SOLID:

• Zasada pojedynczej odpowiedzialności
• Zasada otwarte-zamknięte
• Zasada podstawienia Liskov
• Zasada segregacji interfejsów
• Zasada odwrócenia zależności

Wykorzystuj koncepcje programowania funkcyjnego. Nawet w językach obiektowych, techniki programowania funkcyjnego mogą prowadzić do czystszego kodu:

• Czyste funkcje bez efektów ubocznych
• Niemutowalne dane
• Funkcje wyższego rzędu
• Kompozycja funkcji

Wybierz odpowiednie podejście do problemu. Paradygmaty obiektowe i funkcyjne mają swoje mocne i słabe strony. Stosuj projektowanie obiektowe, gdy musisz modelować złożone domeny z zachowaniem. Stosuj podejścia funkcyjne do przetwarzania i transformacji danych. Wiele nowoczesnych języków wspiera podejście hybrydowe, pozwalając na użycie najlepszego narzędzia do każdej części systemu.

10. Rozważaj współbieżność ostrożnie

Współbieżność to strategia rozdzielania. Pomaga nam oddzielić, co jest robione, od tego, kiedy jest robione.

Zrozum wyzwania współbieżności. Programowanie współbieżne wprowadza złożoność i potencjalne subtelne błędy. Typowe problemy to:

• Warunki wyścigu
• Zakleszczenia
• Przegapione sygnały
• Problemy z widocznością pamięci

Oddzielaj kwestie współbieżności. Trzymaj kod związany z współbieżnością oddzielnie od innego kodu. To ułatwia rozumienie i testowanie. Używaj abstrakcji takich jak Executors, Futures i Actors do zarządzania współbieżnością, zamiast pracować z surowymi wątkami.

Preferuj niemutowalność i czyste funkcje. Niemutowalne obiekty i czyste funkcje są z natury bezpieczne w wątkach. Eliminują wiele problemów współbieżności, unikając współdzielonego stanu mutowalnego. Gdy mutowalny stan jest konieczny, używaj odpowiednich technik synchronizacji i rozważ użycie zmiennych atomowych lub kolekcji współbieżnych.

Ostatnia aktualizacja: January 22, 2025