Guida allo stile del codice

Questa guida contiene informazioni e linee guida per la scrittura di codice per {{ nome_formale }}.

Stile di codifica

BeeWare segue PEP 8 nel nostro codice base, tranne che per la lunghezza delle righe, che è stata estesa da 79 a 88 caratteri. Utilizziamo Ruff per applicare le convenzioni PEP 8 ove possibile. Quando si esegue il commit del codice, pre-commit eseguirà dei controlli, incluso Ruff. Ove possibile, questo formatterà automaticamente il codice per garantire che soddisfi i nostri standard di formattazione e stile. È possibile configurare alcuni IDE per eseguire automaticamente Ruff al momento del salvataggio, il che può aiutare nel processo.

Tenete presente che la parte più importante della PEP 8 è Sezione 0: Una stupida coerenza è il folletto delle piccole menti. Ci sono situazioni in cui rimanere coerenti con la PEP 8 non ha senso ed è importante capire che, quando è il caso, è accettabile, e talvolta preferibile, scrivere codice non in linea con le regole elencate. Sapere quando essere incoerenti con queste regole è importante quanto mantenere la coerenza nella maggior parte delle situazioni.

Ciò si riflette, ad esempio, nelle convenzioni di denominazione. Le librerie BeeWare devono spesso fungere da ponte con altri linguaggi. Quando si realizzano wrapper per altri linguaggi, è preferibile (e in alcuni casi necessario) seguire le convenzioni di denominazione del linguaggio di destinazione, piuttosto che quelle di Python. Ad esempio, quando si chiama o si fa riferimento a codice Java, le funzioni dovrebbero seguire la convenzione di Java che prevede l'uso di mixedCase, anziché quella della PEP 8 che prevede snake_case.

Seguiamo l'ortografia statunitense per i nomi delle API, le variabili, ecc.

Ci sono anche alcune aggiunte specifiche per BeeWare alla PEP 8:

Suddivisione delle chiamate di funzione lunghe

Quando una chiamata di funzione con più di un argomento non può essere contenuta in una singola riga, inserisci ogni argomento su una riga separata, aggiungendo una virgola alla fine dell'ultimo argomento. Ruff consente (e suggerisce) un formato in cui più argomenti sono raggruppati su una riga:

my_function(
    arg1, arg2, arg3
)

Questo stile non dovrebbe essere utilizzato. È preferibile invece distribuire gli argomenti su una riga ciascuno, aggiungendo una virgola finale all'ultimo argomento:

my_function(
    arg1,
    arg2,
    arg3,
)

Suddivisione di stringhe lunghe

Quando un argomento di tipo stringa deve essere suddiviso su più righe per rispettare i limiti di lunghezza delle righe, racchiudere le stringhe concatenate tra parentesi, in modo che sia chiaro che si tratta di un unico argomento. In altre parole, preferiamo:

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

sopra:

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

Cose da evitare

Cerchiamo di evitare il più possibile i moduli utils, con la consapevolezza che a volte sono inevitabili. L'alternativa preferita è quella di trovare un posto per la funzione in un altro punto del codice sorgente, invece di usare un modulo utils.

Come regola generale, cerchiamo di evitare o rimandare qualsiasi codice di inizializzazione costoso, al fine di ottenere un avvio più rapido dell'app. Ad esempio, i moduli nel pacchetto toga-core vengono caricati in modo "lazy" (ritardato): vengono importati solo quando richiesti, anziché tutti in anticipo. Ciò accelera l'avvio e richiede tempo solo per ciò che l'app sta effettivamente utilizzando.