W poprzednim wpisie skupiliśmy się na popularnych standardach C++. We wcześniejszym artykule omawialiśmy dlaczego standaryzacja jest pożądana. Tym razem przedstawimy subiektywnie dobrane najpopularniejsze standardy języka Python.

Standardy języka Python

W przypadku tego języka kwestia standaryzacji jest ustandaryzowana w dużej mierze przez społeczność oraz instytucję BDFL.

Dokumenty PEP

Dokumenty Python Enhancement Proposal służą do prezentowania propozycji dotyczących języka, ekosystemu oraz całej społeczności Python-a. Pomimo, że pierwotnie dokumenty PEP były kierowane do programistów interpretera CPython, jednak zostały przyjęte przez szeroką rzeszę programistów na całym świecie.

PEP 8 – konwencja stylu kodu Python

Dokument został opublikowany na tej stronie. Rekomendacje, na których bazuje ten dokument, opracowali Guido van Rossum oraz Barry Warsaw. Nadrzędnym celem zawartym w dokumencie jest sprawienie, by kod źródłowy był czytelny, przejrzysty oraz spójny. Dokument reguluje między innymi następujące kwestie:

• Rozmiar wcięcia w kodzie wynosi 4 spacje.
• Maksymalny rozmiar wiersza to 79 znaków.
• Reguły używania polecenia import:
  • umieszczone na początku pliku
  • grupowanie i kolejność: moduły biblioteki standardowej, moduły innych bibliotek, moduły lokalne,
  • używanie nazw bezwzględnych oraz unikania wykorzystania symboli wieloznacznych (ang. wildcards).
• Unikanie nadmiarowych białych znaków (ang. whitespace).
• Ważne jest zachowanie zgodności komentarzy z modyfikowanym kodem.
• Komentarze typu inline powinny być używane oszczędnie.
• Nazwy powinny odzwierciedlać używanie w przeciwieństwie do implementacji.
• Użycie notacji CamelCase dla klas oraz lowercase_with_underscore dla nazw funkcji oraz zmiennych.
• Niepubliczne atrybuty klasy powinny zawierać podkreślenie jako przedrostek.

Ostatnia część dokumentu zawiera praktyczne wskazówki dotyczące między innymi instrukcji porównania, wyjątków adnotacji typów.

PEP 20 – Zen Pythona

Ten dokument jest zwięzły i treściwy. Zawiera 19 następujących zasad Guido van Rossum-a:

1. Piękne jest lepsze od brzydkiego.
2. Jawne jest lepsze od ukrytego.
3. Proste jest lepsze od złożonego.
4. Złożone jest lepsze od skomplikowanego.
5. Płaskie jest lepsze od zagnieżdżonego.
6. Rzadkie jest lepsze od gęstego.
7. Czytelność ma znaczenie.
8. Przypadki szczególne nie są wystarczająco szczególne, aby łamać zasady.
9. Chociaż praktyczność bije czystość.
10. Błędy nigdy nie powinny być ignorowane.
11. Chyba, że są wyraźnie wyciszone.
12. W obliczu niejednoznaczności odrzuć pokusę zgadywania.
13. Powinien istnieć jeden — a najlepiej tylko jeden — oczywisty sposób, aby to zrobić.
14. Chociaż ten sposób może nie być oczywisty na początku, chyba że jesteś Holendrem.
15. Teraz jest lepiej niż nigdy.
16. Chociaż nigdy jest często lepiej niż właśnie teraz.
17. Jeśli implementacja jest trudna do wyjaśnienia, to jest to zły pomysł.
18. Jeśli implementacja jest łatwa do wyjaśnienia, może to być dobry pomysł.
19. Przestrzenie nazw to jeden z najlepszych pomysłów — zróbmy ich więcej!

Autor zasad kładzie przede wszystkim nacisk na czytelność, zrozumienie oraz prostotę kodu. Kod napisany zgodnie z tymi zasadami określany jest mianem pythonic. Więcej informacji na ten temat można znaleźć na Wikipedii.

PEP 257 – konwencje docstring

Dokument został opublikowany na następującej stronie. W pierwszej kolejności wyjaśnia, że docstring to ciąg znaków umieszczony jako pierwsze wyrażenie w definicji modułu, funkcji, klasy lub metody, który zostanie umieszczony jako atrybut obiektu reprezentującego ten element. Celem dokumentu jest ustandaryzowanie struktury elementów docstring oraz określenie co powinny zawierać.

Google Python Style Guide

Swoje zalecenia firma Google opublikowała na następującej stronie. Stawia przede wszystkim na narzędzia wspomagające styl kodu. W tym celu opracowała reguły formatowania dla edytora Vim, dopuszcza używanie narzędzi typu black i pyink oraz określiła ustawienia reguł programu pylint. Następnie w dokumencie opisane są najważniejsze elementy:

• importowanie tylko pakietów oraz modułów w przeciwieństwie do pojedynczych typów, klas i funkcji,
• importowanie pakietów używając pełnej ścieżki zamiast ścieżek względnych,
• wyjątki powinny być rozważnie wykorzystywane,
• należy unikać zmiennych globalnych (ang. mutable global state),
• wyrażenia warunkowe (operator trójargumentowy) może być wykorzystywany do prostych wyrażeń,
• właściwości mogą być używane w przypadku trywialnych obliczeń lub prostej logiki,
• dekoratory (adnotacje) powinny być używane z rozwagą, ponieważ mogą prowadzić do zaskakującego niejasnego zachowania kodu,
• należy unikać zaawansowanych oraz niestandardowych funkcjonalności języka Python, ponieważ kod wówczas jest trudniejszy do czytania, zrozumienia i debugowania,
• tylko jedno wyrażenie w pojedynczej linii – nie należy używać średnika do umieszczania dwóch wyrażeń w jednej linii,
• docstring powinien być redagowany zgodnie ze szczegółowymi wytycznymi,
• należy unikać konkatenacji ciągów znaków używając operatorów + oraz +=,
• ciągi f-string są zabronione dla loggerów używających symbolów zastępczych % (ang. placeholders),
• komentarze TODO należy używać w przypadku kodu tymczasowego, stanowiącego rozwiązanie krótkoterminowe lub wystarczająco dobrego, ale nie idealnego.

Firma w swoich rekomendacjach wskazuje na czytelność kodu oraz na automatyczne formatowanie oraz walidację kodu. Dodatkowo wskazuje na kilka dobrych praktyk wspomagających wydajność kodu.

LLVM Coding Standards

Standard kodu dla projektu LLVM został opublikowany na tej stronie. Według opracowania kod ma być zgodny z PEP 8 oraz sformatowany przy użyciu programu black.

The Hitchhiker’s Guide to Python!

Dokument jest opracowywany przez społeczność programistów Python. Został opracowany w formie przewodnika ekosystemu zawierającego między innymi wskazówki dotyczące rozpoczęcia pracy z językiem, instalacji środowiska deweloperskiego, scenariusze użycia języka (przykładowe aplikacje), wskazówki jak wdrażać oprogramowanie (ang. shipping and deployment) oraz źródła z informacjami do dalszego rozwoju.

Nas interesuje sekcja Writing Great Python Code. Najważniejsze informacje zawarte w tej sekcji to:

• rekomendowana struktura repozytorium python-owego projektu,
• polecenia import powinny być stosowane tylko do modułów,
• funkcje i procedury powinny zawierać możliwie najmniejszą liczbą ukrytych kontekstów i efektów ubocznych,
• należy unikać stosowania tej samej nazwy zmiennej do różnych rzeczy,
• preferowany jest sposób najbardziej jawny oraz bezpośredni (ang. straightforward and explicit),
• zalecane jest jedno wyrażenie na linię,
• należy unikać magicznego kodu wykorzystującego wysoce zaawansowane funkcje języka,
• w przypadku niepoprawnego przepływu kodu zaleca się wczesne wyjście z funkcji (ang. early return),
• w przypadku normalnego przepływu zaleca się stosowanie pojedynczego miejsca do zwracania znaczących wartości,
• zaleca się stosowanie PEP 8 oraz PEP 20 oraz narzędzi formatujących oraz weryfikujących kod zgodnie z tymi dokumentami,
• dokcstring powinien być pisany zgodnie z PEP 257.

Spostrzegawczy czytelnicy zauważą, że podręcznik autostopowicza zawiera części wspólne z rekomendacjami Google, przy czym opisuje rekomendacje w sposób ogólny. Opracowanie należy traktować nie tylko jako zestaw dobrych praktyk, a jako podręcznik jak należy korzystać z języka Python. Większość zawartych w nim informacji kierowanych jest do początkujących programistów niemniej, zwłaszcza w stosunku do sekcji dotyczących narzędzi, bardziej zaawansowani programiści również znajdą coś ciekawego.

Podsumowanie

Najważniejsze standardy kody Python w porównaniu do C++ są ze sobą w dużej mierze zgodne oraz wskazują na PEP jako podstawę do stosowania. Również w Python-ie czytelność, zrozumienie oraz prostota kodu jest istotna, a komentarze pełnią istotną rolę w osiągnięciu tego celu.

Twój zespół jest zbyt zajęty lub nie wie jak wdrożyć powyższe techniki?