Jak formatować kod Python – styl kodu z PEP 8

Jak formatować kod, żeby był zjadliwy do późniejszego odczytania? To nie takie proste, jak myślisz. Czy zdarzyło Ci się kiedyś pisać kod, później odłożyć go, bo… życie, a po powrocie nie miałeś_aś pojęcia Co autor miał na myśli? Albo pracujesz w zespole i używacie Gita do kontroli wersji. Robisz drobną zmianę, odpalasz Merge Request i okazuje się, że masz 10496 zmian i cały kod na czerwono, bo ktoś w Twoim (albo TY!) używa tabu zamiast spacji i zaznaczyło Ci wszystkie wcięcia? W efekcie merdż, który powinien zająć 2 minuty, zajmuje kilka godzin, a ty trzymasz kciuki, żeby przypadkiem nie nadpisać czegoś ważnego.

Właśnie dlatego styl kodu ma znaczenie! Możesz mieć kod, który odkrywa tajemnicę Atlantydy, ale jeśli jest napisane bez zachowania clean code’u i stylowania, nikt oprócz Ciebie (a nawet włącznie z Tobą po kilku tygodniach) nie będzie w stanie do odczytać i zdebugować.

Co to PEP 8

PEP 8 (od ang. Python Enhancement Proposal 8) to oficjalny przewodnik po stylu kodowania języka Python. Określa konwencje dotyczące formatowania kodu, nazewnictwa zmiennych i innych aspektów, które wpływają na czytelność i spójność kodu, co ułatwia pracę w zespołach programistycznych.

PEP 8 to zbiór rekomendacji, a nie obowiązkowych reguł, choć zaleca się ich przestrzeganie. Ułatwia to odczytanie i zrozumienie kodu przez innych, a także pomaga uniknąć błędów wynikających z niekonsekwentnego formatowania. Ostatnia aktualizacja miała miejsce 4. kwietnia 2025.

Co zawiera PEP 8?

PEP 8 to więcej niż tylko kłotnia o spacje zamiast taba. To cała kolekcja zasad dotyczących tego, jak pisać kod w Pythonie, żeby inni nie czytali tego jak hieroglify egipskie. Znajdziesz tam wskazówki na temat wcięć, długości linii, importów, cudzysłowów, spacji, nazw zmiennych i klas, komentarzy, a nawet tego, jak formatować docstringi (choć to akurat jest dokładnie opisane w drugim PEP-ie – PEP257) i gdzie postawić przecinek.

Krótko mówiąc – wszystko, co sprawia, że Twój kod wygląda jak Python, z których chce się pracować i żeby koledzy z pracy nie dosypali Ci czegoś do kawy po Twoim commit’cie.

Jak formatować kod zgodnie z PEP 8

Zasada	Co zaleca PEP 8?
Wcięcia	4 spacje
Długość linii	79 znaków (kod) / 72 (komentarze). Dopuszczalne 99 lub 120 w projektach wewnętrznych – ale ustal to w zespole
Importy	3 bloki: stdlib → third-party → lokalne; pusta linia między blokami.
Cudzysłowy	' ' = " " – wybierz jedną opcję i trzymaj się tego.
Whitespace	Bez zbędnych spacji przed przecinkiem i w nawiasach.
Trailing commas	Tak, jeśli pomaga w diffach (np. listy wielowierszowe).
Nazewnictwo	snake_case dla funkcji i zmiennych, PascalCase dla klas, UPPER_CASE dla stałych.
Komentarze & docstringi	Krótkie, aktualne, bez oczywistości i lania wody -> dokładny opis w PEP257.
Adnotacje typów	Rekomendowane (więcej o tym w PEP484), ale nie obowiązkowe.

Importy

Importy powinny być podzielone na trzy osobne grupy: (1) biblioteka standardowa Pythona, (2) pakiety zewnętrzne (np. requests, numpy), (3) moduły lokalne projektu. Między każdą z tych grup należy dodać jedną pustą linię.

Cudzysłowy

Można stosować zarówno pojedyncze, jak i podwójne cudzysłowy, ale najlepiej wybrać jeden styl i trzymać się go w całym projekcie.

Whitespaces (spacje, entery itp.)

Należy unikać zbędnych spacji, np. przed przecinkami, wewnątrz nawiasów czy wokół operatorów.

Trailing commas (przecinki na końcu)

W przypadku struktur wielowierszowych (takich jak listy, słowniki czy krotki), należy dodawać przecinek na końcu ostatniego elementu.

Nazewnictwo

Styl nazewnictwa ma znaczenie:
– snake_case dla zmiennych i funkcji,
– PascalCase dla klas,
– UPPER_CASE dla stałych.

Komentarze i docstringi

Komentarze powinny być konkretne, aktualne i przydatne.
Dla funkcji i klas warto stosować docstringi zgodne z PEP257.

Adnotacje typów

Warto stosować adnotacje typów (zgodnie z PEP484) – szczególnie w większych projektach.

Narzędzia do autoformatowania kodu – Black, Autopep8 i YAPF

PEP 8 to zbiór zasad dotyczących stylu kodu w Pythonie – ale sam w sobie nie jest narzędziem. Dlatego powstały formattery, czyli programy, które automatycznie dostosowują kod do określonego stylu. Trzy najpopularniejsze to Black, Autopep8 i YAPF.

Black to narzędzie, które opiera się na zasadzie „jedyny słuszny styl” – działa bez większych opcji konfiguracyjnych, stosuje „własną interpretację PEP 8” (czyt. nie stosuje wszystkich zasad, a niektóre po prostu łamie), np celowo narzuca limit 88 znaków w linii (zamiast 79) i nie pozwala tego zmienić.

Plusy i minusy

+ Dzięki temu kod wygląda zawsze spójnie i nie trzeba podejmować decyzji estetycznych – co znacząco ułatwia pracę w zespołach.
– Nie daje niemal żadnych opcji dostosowania na zasadzie take it or leave it. Czasem też formatuje kod w sposób zbyt mechaniczny, np. dzieli krótkie wyrażenia na wiele linii.

---

Autopep8 próbuje automatycznie poprawiać kod tak, aby był zgodny z zasadami PEP 8. To dobre narzędzie do „szybkiego czyszczenia” kodu, zwłaszcza starszego, i nie ingeruje tak silnie w strukturę jak Black.

Plusy i minusy

+ Ma więcej opcji customizacji niż Black.
– Często wymaga ręcznego poprawiania kodu po użyciu. Ma też obsuwy w aktualizacji i np. nie obsługuje nowszych konstrukcji Pythona (jak match/case) tak dobrze, jak Black.

---

YAPF (ang. Yet Another Python Formatter), stworzony przez Google, daje najwięcej opcji konfiguracyjnych i próbuje zachować strukturę kodu w sposób bardziej „estetyczny”, nawet jeśli oznacza to odejście od literalnego PEP 8.

Plusy i minusy

+ Próbuje osiągnąć kompromis pomiędz zgodnością z dokumentacją PEP 8, spójnością kodu i łatwością jego czytania.
– Wymaga więcej konfiguracji i decyzji ze strony użytkownika. Czasem powoduje dziwne zmiany, jeśli kod był wcześniej formatowany za pomocą innego narzędzia.

---

Każdy z formatterów ma inne priorytety – dla Black najważniejsza jest spójność, Autopep8 stawia na zgodność z PEP 8, a YAPF na estetykę i konfigurowalność. Wybór formattera zależy od potrzeb projektu – nie ma rozwiązania idealnego, ale najgorsze to nie wybrać żadnego.

Aktualizacje PEP 8 i kwestie sporne

Python jest open source’m i jako taki, wsłuchuje się w opinie swoich użytkowników (i chwała mu za to!). Na forum dyskusyjnym Pythona trwają gorące dyskusje na temat aktualizacji PEP 8 i dwa największe spory dotyczą długości linii i wyrównania operatorów.

• Długość linii: Aktualnie PEP 8 zaleca ograniczenie długości linii do 79 znaków. To pomaga czytać kod, zwłaszcza jeśli masz otwartych kilka ekranów jeden obok drugiego. Jednak większość programistów pracuje na dużych monitorach i takie nadgorliwe łamanie linii sprawia, że kod ciągnie się kilometrami. W dodatku do limitu 79 znaków wliczają się również wcięcia, co dodatkowo zmniejsza dopuszczalną liczbę znaków.
• Wyrównywanie operatorów: Aktualnie PEP 8 nie zaleca wyrównywanie operatorów (np. znaku =) w celu zachowania prostoty i unikania zbędnego białego znaku. Czasem jednak wyrównanie operatorów znacząco poprawia to czytelność, np. przy deklaracji powiązanych zmiennych.

Trudno powiedzieć, która opcja wygra i, oczywiście, stosowanie danej zasady PEP 8 nie jest obowiązkowe. Dlatego polecam wziąć udział w dyskusji i cieszyć się z tego, że mamy demokrację i możliwość wypowiadania się w kwestiach dla nas ważnych.

PEP 8 na szybko

Nie masz ochoty wczytywać się w przewodniki i po prostu chcesz, żeby Twój kod wyglądał na tyle dobrze, żebyś dostał_a pracę? No problem! Zapamiętaj i stosuj poniższe zasady i jesteś w domu:

• Wcięcie z 4 spacji – żadnych tabów.
• 79 znaków w linii.
• Importy w trzech blokach.
• snake_case dla zmiennych i funkcji, PascalCase dla klas, UPPER_CASE dla stałych.
• Docstring, gdy funkcja robi coś bardziej ambitnego.
• Komentarz krótki i konkretny, najlepiej zgodnie z PEP257.
• Razem z zespołem dodajcie formatter do pre-commit’a.

---

Co dalej?

→ Zapisz się do naszego newslettera, żeby nigdy nie przegapić żadnego wartościowego artykułu.

→ Zajrzyj do sekcji Kariera w AI, gdzie znajdziesz konkretne materiały o zmianach na rynku pracy – w Polsce i na świecie – oraz ścieżkach kariery związanych ze sztuczną inteligencją (nie tylko jako programista!).

→ A jeśli chcesz pisać modele i pracować jako Architekt AI, ale nie wiesz, od czego zacząć (lub utknąłeś gdzieś na ścieżce), odwiedź dział Nauka AI – czeka tam wiedza, ciekawostki i realne wsparcie.

---

! Uwaga

Niniejszy ebook ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani oferty pracy w rozumieniu przepisów krajowych lub unijnych.
Przy tworzeniu niniejszego artykułu korzystano ze wsparcia narzędzi opartych na sztucznej inteligencji – m.in. w zakresie porządkowania treści, analizy źródeł, przyspieszenia redakcji i wyszukiwania źródeł Jednak wszelkie decyzje dotycząca treści, interpretacji i ostatecznej formy zostały podjęte przez człowieka.