Pravidla pro styl kódu

Tato příručka obsahuje informace a pokyny pro psaní kódu pro BeeWare.

Styl kódu

BeeWare se řídí PEP 8 v našem kódovém základu, s výjimkou délky řádku, která byla rozšířena z 79 na 88 znaků. K prosazování konvencí PEP 8 používáme Ruff, kde je to možné. Když odesíláte svůj kód, pre-commit provede kontroly, včetně Ruff. Pokud je to možné, automaticky naformátuje váš kód, aby splňoval naše standardy formátování a stylu. Některé IDE můžete nastavit tak, aby při ukládání automaticky spouštěly Ruff, což vám může s tímto procesem pomoci.

Mějte na paměti, že nejdůležitější částí PEP 8 je Sekce 0: Pošetilá konzistence je strašákem malých myslí. Existují situace, kdy dodržování PEP 8 nedává smysl, a je důležité pochopit, že v takových případech je přijatelné, a někdy dokonce žádoucí, psát kód, který není v souladu s uvedenými pravidly. Vědět, kdy být nekonzistentní s těmito pravidly, je stejně důležité jako udržovat konzistenci ve většině situací.

Jedním z projevů tohoto přístupu jsou konvence pojmenování. Knihovny BeeWare často potřebují propojit s jinými jazyky. Při vytváření obalových funkcí pro jiné jazyky je žádoucí (a v některých případech i nezbytné) řídit se konvencemi pojmenování cílového jazyka, nikoli jazyka Python. Například při volání nebo odkazování na kód v Javě by funkce měly používat v Javě preferované značky mixedCase, nikoli značky snake_case, které doporučuje PEP 8.

Při pojmenovávání API, proměnných atd. se řídíme americkým pravopisem.

K PEP 8 existují také některé doplňky specifické pro BeeWare:

Rozdělení dlouhých volání funkcí

Pokud se volání funkce s více než jedním argumentem nevejde na jeden řádek, umístěte každý argument na samostatný řádek a za poslední argument vložte čárku. Ruff povoluje (a dokonce doporučuje) formátování více argumentů na jednom řádku s přenosem:

my_function(
    arg1, arg2, arg3
)

Tento styl by se neměl používat. Místo toho rozložte argumenty tak, aby byl každý na samostatném řádku, a to přidáním čárky na konec posledního argumentu:

my_function(
    arg1,
    arg2,
    arg3,
)

Rozdělení dlouhých řetězců

Pokud je třeba řetězcový argument rozdělit na více řádků, aby splňoval požadavky na délku řádku, uzavřete zřetězené řetězcové literály do závorek, aby bylo zřejmé, že se jedná o jediný argument. Upřednostňujeme tedy:

my_function(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

přes:

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    second_argument,
)

Věci, kterým je třeba se vyhnout

Snažíme se co nejvíce vyhýbat modulům utils, ale chápeme, že někdy jsou nevyhnutelné. Preferovanou alternativou je najít danou funkci jinde ve zdrojovém kódu, místo použití modulu utils.

Obecně se snažíme vyhnout nebo odložit jakýkoli nákladný inicializační kód, abychom dosáhli rychlejšího spuštění aplikace. Například moduly v balíčku toga-core jsou „načítány až při potřebě“ – jsou importovány až po vyžádání, nikoli předem. To urychluje spuštění a čas se věnuje pouze tomu, co aplikace skutečně používá.