Otwierasz funkcję, która ma obsłużyć jedno kliknięcie, a po kilku minutach wciąż nie wiadomo, czy zapisuje dane, wysyła żądanie, czy tylko przygotowuje komunikat. Clean code to kod, którego intencję da się odczytać z nazw, struktury i przepływu, choć sama zgodność z regułami formatowania jeszcze tego nie zapewnia. Gdy ten warunek nie jest spełniony, każda poprawka zaczyna przypominać poruszanie się po pokoju z wyłączonym światłem.

Czytelny kod prowadzi od nazwy do decyzji bez zbędnych domysłów
- Intencja funkcji powinna być widoczna bez analizowania całego projektu.
- Formatowanie porządkuje zapis, lecz nie naprawia złych nazw ani zbyt szerokiej odpowiedzialności.
- Małe funkcje ułatwiają testowanie, przeglądanie zmian i późniejsze poprawki.
- Automatyczne narzędzia wykrywają część problemów, ale nie oceniają dobrze sensu biznesowego kodu.
- Małe zmiany pomagają utrzymać czytelność podczas rozwoju projektu.
Formatowanie porządkuje kod, lecz intencję budują nazwy
Najłatwiej pomylić czysty kod z kodem, który po prostu wygląda równo. Wcięcia, odstępy i kolejność importów pomagają szybko przesuwać wzrok po pliku, jednak nie odpowiedzą na pytanie, co właściwie robi dana funkcja.
PEP 8 opisuje między innymi nazewnictwo funkcji i zmiennych, grupowanie importów, stosowanie spacji oraz limit długości linii wynoszący standardowo 79 znaków. To dobry punkt startu dla projektu w Pythonie, lecz nadal pozostaje zestawem konwencji zapisu, a nie pełną metodą projektowania kodu. ([peps.python.org](https://peps.python.org/pep-0008//?utm_source=openai))
Porównaj dwa przykłady:
def calc(x, y):
return x * (1 - y)
def calculate_net_price(gross_price, discount_rate):
return gross_price * (1 - discount_rate)
Druga wersja nie jest dłuższa na tyle, by utrudnić lekturę, a od razu ujawnia sens obliczenia. Nazwa powinna odpowiadać na pytanie, co reprezentuje wartość albo jaką decyzję podejmuje funkcja. Skróty typu cfg, tmp czy data bywają wygodne podczas prototypowania, ale szybko tracą sens, gdy plik zaczyna obsługiwać kilka przypadków.
Uważam, że początkujący programista więcej zyskuje na poprawie nazw niż na mechanicznym skracaniu funkcji do określonej liczby wierszy. Krótki kod z nazwami a, b i result potrafi wymagać większego wysiłku niż dłuższy fragment, w którym domena jest nazwana wprost.
Nazwy powinny zdradzać decyzję, którą podejmuje funkcja
Funkcja o nazwie process_data() może oznaczać niemal wszystko. Jeżeli w środku waliduje dane, zapisuje rekord w bazie i wysyła e-mail, nazwa ukrywa problem zamiast go rozwiązywać.
Lepszy zapis rozdziela działania według intencji:
def validate_order(order):
...
def save_order(order):
...
def send_confirmation(order):
...
Każdą funkcję da się wtedy opisać jednym zdaniem. Gdy opis wymaga słów „a potem”, „chyba że” i „w międzyczasie”, odpowiedzialność prawdopodobnie została rozciągnięta zbyt szeroko.
Ta zasada działa również w projektach wykorzystujących sensory, zdarzenia i interfejs użytkownika. W kodzie obsługującym prototyp rzeczywistości rozszerzonej nazwa handle_tap_on_virtual_object() przekazuje więcej informacji niż ogólne handle_event(). Dzięki temu łatwiej odróżnić gest użytkownika od zdarzenia pochodzącego z kamery lub warstwy renderującej.
Przy nazwach booleanów dobrze działa forma, która brzmi jak pytanie:
is_authenticatedopisuje stan,has_permissionmówi o uprawnieniu,should_retrywyraża decyzję,can_publishwskazuje możliwość wykonania operacji.
Unikaj nazw, które wymagają komentarza do odgadnięcia znaczenia. Jeżeli komentarz tłumaczy, że limit = 3 oznacza maksymalną liczbę ponowień połączenia, lepsze będzie MAX_RETRY_ATTEMPTS = 3. Komentarz może wtedy wyjaśniać powód ograniczenia, zamiast zastępować nazwę.
Jedna funkcja powinna mieścić jeden przebieg myślowy
Najbardziej podejrzany fragment często zaczyna się niewinnie. Funkcja pobiera dane, sprawdza uprawnienia, przelicza wartości, zapisuje wynik i jeszcze buduje odpowiedź dla użytkownika. Każdy krok osobno jest zrozumiały, ale razem tworzą ścieżkę, której trudno zaufać.
Przyjąłbym prostą regułę roboczą: jeśli funkcja ma więcej niż dwa poziomy zagnieżdżenia albo łączy walidację, zapis i komunikację, rozdziel ją na osobne kroki. Nie jest to norma języka Python, tylko praktyczny sygnał, że kod zaczyna wymagać mapy.
def register_user(user):
if user:
if user.email:
if is_valid_email(user.email):
save_user(user)
send_email(user.email, "Welcome")
return {"status": "ok"}
return {"status": "error"}
Wersja z wcześniejszym wyjściem z funkcji pokazuje warunki bez piętrowania bloków:
def register_user(user):
if user is None:
return {"status": "error"}
if not user.email:
return {"status": "error"}
if not is_valid_email(user.email):
return {"status": "error"}
save_user(user)
send_email(user.email, "Welcome")
return {"status": "ok"}
Jeżeli komunikaty błędów są różne, można wydzielić walidację do osobnej funkcji. Wtedy główny przebieg zaczyna przypominać opis procesu, a testy nie muszą za każdym razem przechodzić przez zapis i wysyłkę wiadomości.
| Sytuacja w kodzie | Prawdopodobna przyczyna lub skutek | Co zrobić |
|---|---|---|
| Funkcja ma ogólną nazwę i przyjmuje wiele argumentów | Odpowiedzialność jest trudna do określenia, a wywołania stają się kruche | Zastąp ogólną nazwę nazwą domenową i rozważ obiekt danych zamiast długiej listy parametrów |
| Warunki są zagnieżdżone na trzech lub większej liczbie poziomów | Główna ścieżka wykonania znika w wyjątkach | Zastosuj wcześniejsze wyjścia albo wydziel predykaty, czyli funkcje odpowiadające na pytania typu is_valid() |
| Każdy blok ma komentarz opisujący oczywistą instrukcję | Kod jest zbyt mało czytelny sam w sobie | Najpierw popraw nazwy i strukturę, a komentarz zostaw tylko dla decyzji, której nie da się odczytać z implementacji |
| Funkcja zapisuje plik i obsługuje kilka rodzajów błędów | Przy zmianie formatu danych łatwo naruszyć obsługę zasobu | Użyj kontekstu with oraz rozdziel operacje wejścia i wyjścia od logiki biznesowej |
Automatyczne narzędzia pomagają, lecz nie rozpoznają intencji
Formatowanie i linting zdejmują z zespołu część powtarzalnych decyzji. Google Python Style Guide opisuje Pylint jako narzędzie do wykrywania błędów i problemów ze stylem, a także wskazuje formatery takie jak Black lub Pyink jako sposób na ograniczenie sporów o układ kodu. ([google.github.io](https://google.github.io/styleguide/pyguide.html?utm_source=openai))
Granica automatyzacji pojawia się wtedy, gdy kod jest formalnie poprawny, lecz źle komunikuje zamiar. Badanie obejmujące 370 zmian poprawiających czytelność w 284 zaakceptowanych pull requestach z 109 repozytoriów wykazało, że SonarQube rozpoznał 26 z nich. W przeliczeniu na 100 podobnych zmian oznacza to około 7 wykrytych i 93 pominiętych. ([arxiv.org](https://arxiv.org/abs/2309.02594?utm_source=openai))
Nie wynika z tego, że SonarQube jest bezużyteczny. Wynika coś bardziej praktycznego: linter może pilnować powtarzalnych reguł, ale człowiek nadal musi ocenić, czy nazwa pasuje do domeny, czy funkcja ma właściwą granicę i czy kod nie ukrywa skutków ubocznych.
W Pythonie czystość obejmuje także zarządzanie zasobami. Dokumentacja Pythona wskazuje, że konstrukcja try...finally pozwala wykonać sprzątanie niezależnie od tego, czy pojawi się wyjątek, a instrukcja with upraszcza bezpieczne zamykanie zasobów. ([docs.python.org](https://docs.python.org/3/tutorial/errors.html?utm_source=openai))
with open("users.txt", encoding="utf-8") as file:
users = file.read()
W takim zapisie sposób obsługi pliku jest widoczny od razu. Osobny komentarz w rodzaju „zamknij plik po odczycie” nie wnosiłby już informacji.
Czytelność spada podczas dużych zmian, więc pracuj małymi krokami
Najlepiej napisany moduł może stracić przejrzystość podczas jednej dużej poprawki. Nowa funkcja trafia do starego pliku, obok niej pojawiają się wyjątki, tymczasowe zmienne i kolejne warunki, a po kilku dniach trudno już odtworzyć pierwotny zamysł.
Badanie ewolucji czytelności obejmujące 25 projektów i około 83 tysięcy commitów wykazało, że zmiany czytelności pojedynczych plików występowały w mniej niż 5% przypadków. Gdy do nich dochodziło, największe ryzyko pogorszenia wiązało się z dużymi commitami wprowadzającymi nowy kod. ([pure.tue.nl](https://pure.tue.nl/ws/files/173794150/Piantadosi2020_Article_HowDoesCodeReadabilityChangeDu.pdf?utm_source=openai))
Ta obserwacja prowadzi do prostego sposobu pracy nad projektem:
- Najpierw dodaj test opisujący zachowanie, które ma pozostać bez zmian.
- Wydziel jedną odpowiedzialność bez równoczesnej zmiany logiki biznesowej.
- Uruchom formatter, linter i testy przed kolejną modyfikacją.
- W pull requeście opisz jednym zdaniem, jaką decyzję ma ułatwić nowa struktura.
- Jeśli diff zaczyna obejmować kilka niezależnych problemów, podziel zmianę na osobne części.
Swoją drogą, mały commit nie oznacza automatycznie dobrego commitu. Jedna funkcja może być bardzo krótka, a mimo to mieszać trzy warstwy aplikacji. Liczy się spójność celu, nie sama liczba zmienionych linii.
Na miejscu osoby rozwijającej mały projekt wybrałbym refaktoryzację wykonywaną tuż przed dodaniem kolejnej funkcji. Wtedy poprawiona struktura od razu dostaje nowe użycie i łatwiej zauważyć, czy uproszczenie faktycznie działa.
Najkrótszy test clean code przed wysłaniem zmian
Przed zamknięciem zadania zadaj sobie pięć pytań:
- Czy nazwa funkcji mówi, jaki problem rozwiązuje?
- Czy da się opisać jej działanie jednym zdaniem bez słowa „i”?
- Czy główna ścieżka kodu jest widoczna bez przewijania wielu bloków?
- Czy komentarz wyjaśnia powód decyzji, a nie powtarza instrukcję?
- Czy osoba, która nie pisała tego fragmentu, wie, gdzie wprowadzić kolejną zmianę?
Jeżeli odpowiedź na ostatnie pytanie brzmi „nie”, formatowanie raczej nie rozwiąże problemu. Uważam, że właśnie wtedy zaczyna się prawdziwa praca nad czystym kodem: od usunięcia domysłów, zanim zamienią się w kosztowną poprawkę.
