Moja ściąga z PEP 8 – część 2

Konwencje nazewnictwa

Istnieją pewne rekomendowane konwencje nazewnictwa w Pythonie. Konwencje te powinny być stosowane do nowo pisanych modułów. Nowo pisane pakiety i moduły powinny być utrzymane w tych konwencjach. Kiedy starsza biblioteka reprezentuje inny styl to przy jej rozszerzaniu powinien być zachowany pierwotny styl w celu wewnętrznej spójności.

Nazwy, których należy unikać:

Nie używać jako nazw zmiennych liter l (L jak Leszek), O (O jak Olga) oraz I (i jak Irena). W przypadku pewnych krojów czcionek litery te są nieodróżnialne od liczby jeden oraz zero.

Nazwy pakietów i modułów.

Moduły powinny mieć krótką nazwę wyłącznie z małych liter. Podkreślenia mogą być używane w nazwach modułów jeśli poprawi to czytelność. Podobnie jest w przypadku pakietów (ang. package) jednak nie zaleca się stosować podkreśleń.

Ponieważ nazwy modułów są mapowane do nazw plików powinny one być odpowiednio krótkie. Zbyt długie nazwy mogą być problemem na starszych wersjach Mac, Windows oraz w DOS.

Kiedy rozszerzeniu napisanym w C/C++ towarzyszy moduł Pythona dodający interfejs wyższego poziomu (bardzo zorientowany obiektowo), nazwa rozszerzenia w C/C++ powinna rozpoczynać pojedynczym podkreśleniem (np. _socket)

Nazwy klas

Prawie że bez wyjątków, nazwy klas powinny mieć nazwę w konwencji CapsWords. Klasy do użytku wewnętrznego powinno poprzedzać pojedyncze podkreślenie (_CapsWord).

Nazwy funkcyj

Nazwy funkcyj powinny być pisane małymi literami ze słowami rozdzielanymi przez podkreślenia, jeśli to konieczne aby zwiększyć czytelność (nazwa, nazwa_funkcji)

Argumenty funkcyj i metod

Zawsze należy używać self jako pierwszego argumentu do metody instancji. Zawsze należy używać cls jako pierwszego argumentu do metody klasy.

Jeśli nazwa argumentu funkcji koliduje z nazwą słowa kluczowego Pythona, zazwyczaj lepiej jest dołączyć pojedyncze podkreślenie na końcu nazwy niż tworzyć nieczytelne skróty lub celowe literówki. W związku z tym print_ jest lepsze niż prnt. Dobrze jeśli uda się uniknąć konfliktu przez użycie synonimu.

Nazwy zmiennych globalnych

Nazwy zmiennych globalnych podlegają tym samym konwencjom co nazwy funkcyj. (Zaleca się aby używać zmiennych globalnych tylko wewnątrz jednego modułu)

Moduły, które są zaprojektowane aby używać ich przez from module import * powinny zawierać mechanizm __all__ aby zapobiec eksportowaniu zmiennych globalnych lub stosować starszą konwencję dołączania przedrostka – pojedynczego podkreślenia (co można chcieć zrobić by wskazać te zmienne globalne jako „niepubliczne”).

Nazwy metod i zmiennych instancyj

Stosować zasady dotyczące nazw funkcyj.

Poprzedzające pojedyncze podkreślenie dla niepublicznych metod i zmiennych instancji.

Unikać konfliktu nazw z podklasą przez użycie podwójnego poprzedzającego podkreślenia aby wywołać mechanizm dekorowania nazw Pythona (Python’s mangling rules).

Stałe

Stałe są deklarowane na poziomie modułu i pisane wielkimi literami z pokreśleniami jako separatorami słów. Np. MAX_OVERFLOW i TOTAL.

Konstrukcja ze względu na dziedziczenie

Zawsze należy zdecydować czy metody i zmienne instancji (wspólne określenie to atrybuty) mają być publiczne czy niepubliczne. W razie wątpliwości należy uczynić atrybut niepublicznym, później łatwiej zrobić z niego atrybut publiczny niż na odwrót.

Publiczne atrybuty to te, co do których należy się spodziewać, że będą użyte przez niezwiązane klienty, ze „zobowiązaniem”, że zmiany w module/pakiecie nie będą powodowały niekompatybilności wstecz. Niepubliczne atrybuty to te, które nie są tworzone w zamierzeniu do użycia przez programy trzecie. Nie ma potrzeby zapewniać, że niepubliczne atrybuty nie zmienią się lub nawet nie będą usunięte.

Używa się terminu „niepubliczny” gdyż tak na prawdę żaden atrybut w Pythonie nie jest prywatny.

Kolejna kategoria atrybutów to te, które są częścią „podklasowego API” („subclass API”) – nazywane w innych językach programowania – protected. Niektóre klasy są przeznaczone do dziedziczenia aby rozszerzać lub modyfikować różne aspekty zachowania klasy. Podczas projektowania takiej klasy należy podjąć wyraźne decyzje dotyczące tego jakie atrybuty mają być publiczne, a które są częścią „podklasowego API”, i które będą na prawdę używane tylko przez klasę bazową.

Biorąc pod uwagę powyższe, oto Pythonowe wskazówki.

• Publiczne atrybuty nie powinny mieć przedniego podkreślenia.
• Jeśli atrybut koliduje ze słowem kluczowym Pythona, należy dołączyć pojedyncze, kończące podkreślenie.

Zobacz powyższe rekomendacje dla nazewnictwa metod klas.

• Dla prostych atrybutów z danymi, najlepiej jest ujawnić po prostu nazwę atrybutu bez skomplikowanych metod typu accessor czu mutator. Należy też mieć na uwadze, że Python daje łatwą możliwość rozszerzania funkcjonalności atrybutu jeśli zajdzie taka potrzeba. W takim wypadku używa się właściwości (properties) aby ukryć funkcjonalną implementację atrybutu za prostą składnią dostępu do atrybutu.
  1. Właściwości (properties) działają tylko w nowego typu klasach
  2. ?
  3. Lepiej unikać używania właściwości do drogich obliczeniowo operacji, zapis atrybutu jest traktowany przez wywołującego (caller) jako niewymagający dużych zasobów obliczeniowych.
• Jeśli klasa w zamierzeniu ma służyć jako przodek (subclass) lecz nie wszystkie atrybuty mają być używane przez podklasę można rozważyć nazwanie ich z podwójnym podkreśleniem na początku nazwy i bez końcowego podkreślenia. To spowoduje wywołanie mechanizmu dekorowania nazwy (mangling), gdzie nazwa klasy jest wdekorowana w nazwę atrybutu. To pomaga unikać kolizji atrybutów gdyby podklasa niezamierzenie zawierała atrybuty o takiej samej nazwie.
  1. Zauważyć należy, że tylko prosta nazwa klasy jest używana w dekorowaniu nazwy, tak więc jeśli podklasa ma zarówno taką samą nazwę klasy jak i nazwę atrybutu nadal istnieje możliwość kolizji nazw
  2. Dekorowanie nazwy czyni pewne zastosowania, jak debugowanie czy __getattr__() mniej wygodnymi. Jakkolwiek algorytm dekorowania nazw jest dobrze udokumentowany i łatwy do wykonania ręcznie.

PEP 8 to jest podręcznik z wytycznymi na temat stylu kodu w Pythonie, a powyższy tekst to moja ściąga z PEP 8, napisana na poziomie mojej wiedzy z języka Python. Ma służyć dla mnie jako pomoc w opanowaniu języka.

Do późniejszego uzupełnienia.