PEP8 – czyli czytelny kod

Jedna ze znanych zasad programowania mówi:

Kod pisze się raz, a czyta wiele razy.

Myślę, że nie ma wątpliwości co do słuszności powyższej tezy. Między innymi opierając się na powyższym, polecam zapoznanie się z dokumentem zawierający dobre praktyki pisania kodu w Pythonie, czyli PEP8. Stosowanie się do zasad opisanych w dokumencie nie sprawi, że nasz kod będzie szybszy, lecz z pewnością dużo szybsza będzie jego późniejsza analiza. Poniżej, bazując na wspomnianym dokumencie, przedstawimy zestaw wybranych podstawowych reguł. Dzięki nim, nie tylko pisanie, ale co ważniejsze czytanie kodu będzie łatwiejsze.

Tabulatory, a może spacje?

Jak wiemy, Python bazuje na wcięciach, które określają konkretne bloki kodu. Rekomendowane jest używanie czterech spacji jako wcięcie, jednocześnie dopuszcza się, w celach zachowania zgodności z już istniejącym kodem, używania tabulatorów. W żadnym wypadku nie można stosować zamiennie spacji i tabulatorów w obrębie jednego pliku, a nawet projektu. Istotne są również wcięcia w przypadku kontynuacji linii kodu w nowym wierszu, gdzie zawsze staramy się dopasować linie do nawiasu otwierającego lub zastosować opcję dodatkowego wcięcia w stosunku do obecnego bloku.

def first_method(range, step=8, 
                           default=1):
    return True
     
def second_method():
    return True

def first_method(range, step=8, 
      default=1):
    return True
 
def second_method():
    return True

Długoś linii: 72, 79, a może 99?

Dokument PEP8 określa maksymalną długość linii jako 79 znaków dla kodu oraz 72 znaki dla linii komentarza. Ograniczenie to wynika z jednej strony z wielkości monitorów, a z drugiej z faktu, iż podczas debugowania czy porównywania kodu często wykorzystujemy podział na dwie kolumny. W tym wypadku przy takich ograniczeniach będziemy widzieć dwie pełne linie na monitorze. Biorąc jednak pod uwagę fakt, że pracujemy na coraz większych monitorach i rozdzielczościch, ograniczenie to jest często rozszerzane do 99 znaków na jedną linię. Jest to również zgodne z dokumentem, zakładając, że cały zespół, w którym pracujemy, będzie stosował się do tej samej reguły.

Jak zawijamy?

W związku z powyższym możemy sobie zadać pytanie, co zrobić w przypadku potrzeby zawinięcia linii. Dokument zaleca wykorzystywania niejawnego zawijania linii, poprzez umieszczenie odpowiedniego wycinka kodu w nawiasach, przez co w przypadku braku zamykającego nawiasu na końcu wiersza, automatycznie będzie czytana nowa linia. Jeśli jednak technicznie nie jesteśmy w stanie tego wykonać, dopuszcza się wykorzystanie odwróconego ‚\’ ukośnika w miejscu złamania linii.

Z komentarzami rzecz jest prosta, gdyż z powodzeniem można używać wielolinijkowych komentarzy, przy użyciu ”’ lub „„„. Istotnym elementem jest również przenoszenie do nowej linii przy operatorach matematycznych. Istotne jest tutaj, aby zawsze operator był na początku linii, a nie zostawał na końcu poprzedniej.

'''
No arguments.
Return always True value.
'''
def first_method():
    result = 4 + 5 + 6 +
                 7 + 8
    return True

# No arguments. \ 
Return always True
 
def first_method():
    result = 4 + 5 + 6 \
                 + 7 + 8
    return True

Puste linie

Dokument zwraca również uwagę na puste linie. Każda funkcja najwyższego poziomu, a także klasy powinny być otoczone z obu stron przez dwie puste linie. Natomiast funkcja znajdujące się w klasie przez jedną pustą linę. Dodatkowo dopuszcza się używanie pustych linii wewnątrz funkcji w celu podkreślenia jej logiki.

def first_method():
    return True
 
def second_method():
    return True
 
 
class MyClass:
...

def first_method():
    return True
def second_method():
    return True
class MyClass:
    ...

Importujemy…

Kolejną istotną informacją jest precyzyjne używanie importów. Każdy import powinien być w osobnej linii, z wyjątkiem importu pojedynczych metod z bibliotek, które mogą być wymieniane po przecinku. Warto także zwrócić uwagę na odpowiednie sortowanie wszystkich importów bibliotek, zgodnie z zasadą:

• Standardowe biblioteki
• Zewnętrzne biblioteki
• Lokalne biblioteki

Zaleca się także używanie absolutnych importów, co w znacznej mierze eliminuje problemy z bibliotekami. 

import pylink
from time import time, timezone
 
import MyLibrary

import MyLibrary
import pylink
from time import time
from time import timezone

To teraz spacje

Warto zwrócić również uwagę na spacje okalające znaki – gdzie stosujemy spacje, a gdzie nie powinniśmy. W nawiasach z reguły unikamy zbędnych spacji, a szczególnie po otwierającym nawiasie i przed zamykającym. Podobnie nie umieścimy spacji przed przecinkami, średnikami czy dwukropkami. Dopuszcza się umieszczenie spacji wokół dwukropka w nawiasie kwadratowych, w przypadku, gdy po obu stronach występują działania arytmetyczne. Jednak należy przy tym pamiętać, że spacje powinny występować po obu stronach. Ponadto w nawiasach kwadratowych wokół operatorów arytmetycznych nie umieszczamy spacji. Odwrotna sytuacja ma miejsce, gdy umieszczamy operatory arytmetyczne w nawiasach okrągłych lub bez nawiasu, wtedy umieszczamy wokół nich spacje. 

result = int(factor) * 8 + 32,4

result=int(factor)*8+32,4

Nazwy zmiennych

W mojej opinii jest to jedna z ważniejszych zasad, która traktuje o konwencji nazw. Zgodnie z dokumentem, poprawne nazwy zmiennych i funkcji powinny być tworzony przy użyciu tak zwanego snake_case. Oznacza to, że każde kolejne słowo powinno być oddzielone podkreśleniem. Z kolei nazwy klas dla odróżnienia będą tworzone przy użyciu CamelCase, czyli każde kolejne słowo będzie rozpoczynało się od wielkiej litery oraz będzie złączone z poprzednim. 

square_result = a * a
cube_result = square_result * a

squareResult = a * a
CubeResult = squareResult * a

Pocieszającym faktem jest to, że większość IDE dba o to, aby te zasady były zachowane. I tak na przykładzie PyCharma, mamy na przykład informacje, o maksymalnej długości linii, o spacjach wokół znaków, lub o odpowiedniej liczbie nowych linii przed/po metodzie. Należy jednak pamiętać, że żadne automatyczne IDE nie zastąpią zdrowego rozsądku. Mam nadzieję, że przedstawiając te kilka praktycznych rad, jak pisać czytelniejszy kod, przekonałem Was chociaż trochę do przeczytania całego dokumentu. Na zakończenie ciekawy cytat Kenta Becka z książki „Refaktoryzacja: Ulepszanie struktury istniejącego kodu„:

Każdy głupek może napisać kod, który jest zrozumiały dla komputera. Dobrzy programiści piszą kod, który jest zrozumiały dla ludzi.

Please leave this field empty

Newsletter

Imię

Adres email *

Sprawdź swoją skrzynkę odbiorczą (albo katalog na spam) i potwierdź swoją subskrypcję.