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:

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(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

ponad:

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    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.