Przewodnik po stylu kodowania

Niniejszy przewodnik zawiera informacje i wytyczne dotyczące pisania kodu dla BeeWare.

Styl kodowania

BeeWare stosuje PEP 8 w naszym kodzie źródłowym, z wyjątkiem długości linii, która została zwiększona z 79 do 88 znaków. W miarę możliwości stosujemy Ruff w celu egzekwowania konwencji PEP 8. Podczas zatwierdzania kodu pre-commit przeprowadza kontrole, w tym Ruff. W miarę możliwości spowoduje to automatyczne sformatowanie kodu, aby zapewnić zgodność z naszymi standardami formatowania i stylu. Niektóre środowiska IDE można skonfigurować tak, aby automatycznie uruchamiały Ruff podczas zapisywania, co może ułatwić ten proces.

Należy pamiętać, że najważniejszą częścią PEP 8 jest Sekcja 0: Głupia spójność jest zmorą małych umysłów. Istnieją sytuacje, w których zachowanie spójności z PEP 8 nie ma sensu i ważne jest, aby zrozumieć, że w stosownych przypadkach dopuszczalne, a czasem nawet preferowane jest pisanie kodu, który nie jest zgodny z wymienionymi zasadami. Wiedza o tym, kiedy należy odstąpić od tych zasad, jest równie ważna jak zachowanie spójności w większości sytuacji.

Jednym z przejawów tego zjawiska są konwencje nazewnictwa. Biblioteki BeeWare często muszą zapewniać integrację z innymi językami. Podczas tworzenia nakładek na inne języki wskazane jest (a w niektórych przypadkach wręcz konieczne) stosowanie konwencji nazewniczych języka docelowego, a nie języka Python. Na przykład podczas wywoływania lub odwoływania się do kodu Java funkcje powinny być zapisywane zgodnie z preferencjami języka Java, czyli mixedCase, a nie zgodnie z zaleceniami PEP 8, które przewidują snake_case.

W nazewnictwie API, zmiennych itp. stosujemy pisownię amerykańską.

W PEP 8 wprowadzono również pewne uzupełnienia dotyczące konkretnie BeeWare:

Chociaż stosowanie adnotacji typów zgodnych z PEP 484 jest opcjonalne, nadal zdecydowanie się je zaleca, zwłaszcza w przypadku wszystkich publicznych interfejsów API.

Poniżej przedstawiono przykład standardowej definicji funkcji zawierającej odpowiednie wskazówki dotyczące typów oraz ciąg dokumentacyjny Sphinx:

def nazwa_funkcji(param1: int, param2: str) -> bool:
"""Przykładowa funkcja z typami i opisem.

:param param1: Pierwszy parametr.
:param param2: Drugi parametr.

:returns: Wartość zwracana. True w przypadku powodzenia, w przeciwnym razie False.
"""

Rozdzielanie długich wywołań funkcji

Jeśli wywołanie funkcji z więcej niż jednym argumentem nie mieści się w jednym wierszu, każdy argument należy umieścić w osobnym wierszu, a po ostatnim argumencie dodać przecinek. Ruff zezwala (i sugeruje) formatowanie wielu argumentów w jednym wierszu z przełamaniem:

my_function(
    arg1, arg2, arg3
)

Nie należy stosować tego stylu. Zamiast tego należy rozdzielić argumenty tak, aby w każdym wierszu znajdował się tylko jeden, dodając przecinek na końcu ostatniego argumentu:

my_function(
    arg1,
    arg2,
    arg3,
)

Dzielenie długich ciągów znaków

Jeśli argument typu ciąg znaków musi zostać podzielony na kilka wierszy, aby spełnić wymagania dotyczące długości wiersza, należy ująć połączone literały ciągu znaków w nawiasy, aby było jasne, że ciąg ten stanowi jeden argument. Innymi słowy, zalecamy następujące rozwiązanie:

my_function(
    (
 "to jest bardzo długi ciąg znaków"
 "rozłożony na dwie linijki"
    ),
    second_argument,
)

ponad:

my_function(
    "to jest bardzo długi ciąg znaków",
    "który rozciąga się na dwie linijki",
    second_argument,
)

Rzeczy, których należy unikać

Staramy się unikać modułów utils w miarę możliwości, rozumiejąc jednak, że czasami są one nieuniknione. Preferowaną alternatywą jest znalezienie miejsca dla danej funkcji w innym miejscu kodu źródłowego zamiast używania modułu utils.

Zasadniczo staramy się unikać lub odkładać na później wszelkie kosztowne kody inicjalizacyjne, aby przyspieszyć uruchamianie aplikacji. Na przykład moduły w pakiecie toga-core są „ładowane leniwie” — są importowane dopiero po zgłoszeniu żądania, a nie z góry. Przyspiesza to uruchamianie i pozwala poświęcić czas tylko na to, czego faktycznie używa aplikacja.

Pisząc komentarze, unikaj używania zaimków w pierwszej osobie liczby mnogiej, takich jak „my” (na przykład pisz „Przeprowadź pętlę” zamiast „Przeprowadzamy pętlę”).

W opisach testów należy określić oczekiwane zachowanie, które każdy test ma wykazać. Nie należy dodawać wstępów typu „Sprawdza, czy” lub „Gwarantuje, że”.

Zastrzegaj odniesienia do zgłoszeń dotyczących mało znanych problemów, w przypadku których zgłoszenie zawiera dodatkowe szczegóły, których nie da się łatwo opisać w opisach funkcji lub komentarzach. Umieść numer zgłoszenia na końcu zdania w następujący sposób:

def test_foo():
 """Tak wygląda docstring testowy (#123456)."""