Nasze kody źródłowe będą się rozrastać. Robić się coraz bardziej rozbudowane oraz zaczną pełnić coraz ciekawszą funkcję. Z czasem będziemy do nich wracać, lub też ktoś inny będzie to robić. W zależności jak napiszemy nasz kod, może on być lekki i przyjemny w czytaniu, lub być czarną skrzynką, której działanie przestało być zrozumiałe nawet dla autora.

Jak pisać kod, który będzie, dla nas i dla innych czytelny?

W Python, jest coś co się nazywa PEP8. Najprościej mówiąc, jest to zbiór wytycznych, jak nasze kody pisać, aby były jak najbardziej czytelne. Poniżej przyjrzymy się najważniejszym kwestiom.

Nazwy

Zmienne, funkcje, klasy oraz inne obiekty, możemy nazywać wielkimi literami, małymi, możemy tworzyć je łącząc kilka wyrazów itd. PEP8 standaryzuje nazewnictwo, jakie powinniśmy stosować, w następujący sposób

ObiektPrawidłowa nazwa według PEP8
zmiennazmienna
moja_zmienna
stałaSTALA
MOJA_STALA
funkcja i metodafunkcja
moja_funkcja
klasaKlasa
MojaKlasa
modułmodul.py
moj_modul.py
pakietpakiet
mojpakiet

Przed wieloma programistami, stoi pokusa aby nazywać zmienne oraz inne obiekty, w krótki, często jedno czy dwu literowy sposób. Np x, czy l3.

PEP8, zaleca aby walczyć z tym, i nazywać zmienne tak, aby odzwierciedlały faktyczne przeznaczenie.

Zamiast:

x = 'Mike'

def c():
    pass

Powinno być

imie = 'Mike'

def pusta_funkcja()
    pass

Jedynym uzasadnionym wyjątkiem, są zmienne stosowane we wzorach matematycznych.

Tab vs spacje

Kody bloków funkcji, klas czy tez pętli, rozpoczynają się od „wcięcia”. Tym „wcięciem” są 4 spacje. Standardowo tabulator, dostarcza nam 8, jednak wiele edytorów jest domyślenie skonfigurowanych tak, aby po naciśnięciu przycisku tabulatora, otrzymać dokładnie 4 spacje.

Puste linie

Puste linii, pomiędzy blokami kodu, zdecydowanie zwiększają jego czytelność. Proste zasady, które możemy stosować, to:

  1. Oddzielaj funkcje oraz definicje klas, podwójnymi pustymi liniami
  2. Funkcję, wewnątrz definicji klas, oddzielaj pojedynczą pustą linią
  3. Bloki kodu, wewnątrz funkcji, które stanowią logiczną całość, oddzielaj pustą linią

Komentarze

Komentarze są dobre. Często kiepskie komentarze, będą lepsze niż ich brak.

W Python, mamy 2 rodzaje komentarzy. Dobrze znane komentarze, zaczynjące sie od #. Są to komentarze jedno linijkowe. Oraz komentarze zaczynające się oraz kończące, pojedyńczym lub podwójny cudzysłowem. Czyli ”’, lub „””.

Te drugie pełnia również funkcję dokumentującą, i dobrą praktyką jest stosowanie ich pod każdą, publiczną definicją funkcji, metody oraz klasy

def przykładowa_funkcja():
    """Ta funkcja nic nie robi.
    jest tutaj tulko po to, 
    aby pokazać komentowanie"""
    # a ten ten komentarz jest zbędny
    return


print("Zastosowanie __doc__\n")
print(przykładowa_funkcja.__doc__)

print("\nZastosowanie help\n")
help(przykładowa_funkcja)

Narzędzia wspomagające

Prawda jest taka, że wielu programistów, w ten czy inny sposób pisze swój kod odstając do wytycznych PEP8. Czasami jest to siła nawyku, czasami programują w wielu językach na raz i ciężko jest trzymać osobną konwencję nazewnictwa dla każdego z nich, a czasami wygoda posiadania swojego stylu pisania.

W całym eko-systemie Python, mamy do dyspozycji, kilka narzędzi, które mogą nasz kod sprawdzić pod kątem spójności z PEP8, a czasem nawet go odpowiednio zmodyfikować.

Dwa przykładowe narzędzia to:

http://pep8online.com/

Jest to strona, na które w prosty sposób możemy sprawdzić spójność naszego kodu z PEP8.

Program autopep8https://pypi.org/project/autopep8/

Który może nasz kod zmodyfikować, aby był w mniejszym lub większym stopniu spójny z PEP8. Instalujemy go bardzo prosto:

$ pip install autopep8

i uruchamiamy poprzez, przykładową komendę:

$ autopep8 –in-place nasz_program.py

Szczegóły PEP8

Natomiast szczegóły odnośnie wytycznych, możemy znaleźć na stronie – https://www.python.org/dev/peps/pep-0008/