PEP 8 i PEP 257,taby czy spacje, docstring

PEP 8 – czyli gramatyka dla programisty

Każdy język ma własną gramatykę, czyli zbiór reguł określających zasady tworzenia wypowiedzi. To samo dotyczy również języków programowania. W przypadku Pythona dokumentami definiującymi reguły gramatyczne są PEP 8 oraz PEP 257.

PEP czyli Python Enhancement Proposal jest oficjalnym dokumentem informacyjnym dla społeczności programistów Pythona. Dokumenty tego typu służą między innymi jako dokumentacja nowych funkcji języka. Aktualnie wydanych zostało ponad 470 PEPs. Ich pełną listę można znaleźć w treści PEP 0.

W tym poście chciałbym zwrócić uwagę na dokumenty PEP 8 (Style Guide for Python Code) oraz PEP 257 (Docstring Conventions). Określają one w jaki sposób powinniśmy tworzyć kod.

Dlaczego warto je znać?

Jedną z zalet wynikającą z istnienia norm gramatyki języka programowania jest czytelność kodu, co jest szczególnie ważne w przypadku omawianego języka, który czytelność stawia na pierwszym miejscu. Konwencje przedstawione w dokumentach PEPs są dobrze przemyślane i zdecydowanie poprawiają czytelność. Co prawda, to czy kod jest czytelny jest względne, jednak dokumenty te zapewniają również jednolitość. Gdy już przyzwyczaimy się do zaproponowanych zasad, będziemy mogli bez problemu analizować kod napisany przez innych programistów.

Spacje czy taby?

Podczas programistycznych dyskusji bardzo częstym powodem do sprzeczek jest sposób tworzenia wcięć w kodzie. Zażarci wielbiciele tabów kłócą się z programistami wolącymi używać spacji. I tutaj rodzi się jeszcze jedna wątpliwość. Czy jeden tabulator powinien być równy czterem spacjom, ośmiu, czy może dwóm spacjom?

fragment serialu Sillicon Valley (produkcja HBO) S03E06

PEP 8 rozwiązuje ten spór na korzyść spacji. Wcięcie w kodzie musi być zrobione za pomocą 4 spacji na poziom wcięcia. Znak tabulacji \t odpowiada ośmiu spacjom, jednak w wersji Python3 nie można łączyć wcięć wykonanych tabulatorem i spacjami.
Na szczęście dla wielbicieli tabów, IDE takie jak PyCharm mogą automatycznie zamieniać znak tabulacji na 4 spacje.

Nazwy zmiennych

Python Software Foundation zdecydowała się na zastosowanie konwencji nazewniczej znanej jako snake_case. Oznacza to, że kilkuwyrazowe nazwy zmiennych i stałych należy rozdzielać podkreśleniem. Wyjątkiem od tego są nazwy klas, gdyż zapisujemy je stosując konwencję CamelCase.

Podczas nazywania zmiennych należy również pamiętać, aby nie stosować słów kluczowych języka ani nazw wbudowanych funkcji i obiektów.

Docstrings

Docstrings (documentation strings) służą do tworzenia dokumentacji funkcji, klas oraz modułów napisanych w Pythonie. Konwencje ich używania opisane są w dokumencie PEP 257. Dokumentacje tego typu zapisujemy w potrójnym cudzysłowie na początku klasy lub funkcji:

Dobrze opisane klasy i funkcje są dużo łatwiejsze do opanowania dla innych programisów korzystających z naszego modułu. Można je odczytać np. za pomocą funkcji help.

Można również skorzystać z własności __doc__.

Dokumentacja modułów

Docstrings służą również do opisywania modułów. Docstring opisujący moduł należy zamieścić na samym początku pliku z kodem.
Służą do tego również zmienne nazywane „dunders”, których nazwa rozpoczyna i kończy się podwójnym podkreśleniem.

Wprowadzenie nazwy modułu spowodowało również zmiany w tekście wypisywanym przez funkcję help:

Formaty dokumentacji

Oczywiście utworzone zostały również formaty dokumentowania kodu mające na celu ujednolicenie powstających dokumentacji. Przedstawię poszczególne formaty docstring na przykładzie prostej funkcji dzielącej pierwszą liczbę całkowitą podaną w parametrach przed drugą liczbę całkowitą, która zwraca liczbę typu float.

  • reST(reStructuredText) – format zalecany przez dokument PEP 287.
  • Google
  • Numpydoc – format stosowany w bibliotece Numpy
  • Epytext – format bazowany na javadoc

Pamiętajcie, że najważniejsze aby w ogóle tworzyć dokumentację, styl jaki wybierzecie nie jest tak istotny. Dokumentacja powinna być przede wszystkim czytelna, a zapewniają to wszystkie wymienione wyżej formaty.

Podsumowanie

W tym poście chciałem jedynie zwrócić Waszą uwagę na zasady obowiązujące w Pythonowym community i na potrzebę ich respektowania. Opisanie wszystkich konwencji przedstawionych w dokumentach PEP 8 i PEP 257 można znaleźć na stronie pep8.org, do przejrzenia której bardzo zachęcam.
Stosowanie się do wprowadzonych zasad może wydawać się trudne, jednak z czasem wchodzi ono w nawyk. Szczególnie pomocne przy tym będzie korzystanie np. z PyCharm lub innego edytora skonfigurowanego tak, aby wskazywał nam miejsca niezgodne z konwencjami. Można tak nawet skonfigurować VIMa, o którym więcej możecie dowiedzieć się z mojego posta 9 funkcji VIMa, które powinieneś znać.

The Zen of Python

A na koniec kilka zasad z PEP 20, do których powinien stosować się każdy programista, niezależnie od technologii ;)



Leave a Reply

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *