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:

Sebbene l'annotazione dei tipi conforme alla PEP 484 sia facoltativa, se ne raccomanda vivamente l'uso, in particolare nelle interfacce API pubbliche.

Di seguito è riportato un esempio di definizione di una funzione standard con indicazioni di tipo corrette e una stringa di documentazione Sphinx:

def nome_funzione(param1: int, param2: str) -> bool:
"""Funzione di esempio con tipi e stringa di documentazione.

:param param1: Il primo parametro.
:param param2: Il secondo parametro.

:returns: Il valore restituito. True in caso di esito positivo, False in caso contrario.
"""

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(
    (
 "questa è una stringa molto lunga"
 "che si estende su due righe"
    ),
    second_argument,
)

sopra:

my_function(
    "questa è una stringa molto lunga"
    "che si estende su due righe",
    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.

Quando scrivi i commenti, evita di usare pronomi in prima persona plurale come "noi" (ad esempio, scrivi "Esegui un ciclo su" invece di "Noi eseguiamo un ciclo su").

Nelle stringhe di documentazione dei test, descrivi il comportamento previsto che ciascun test deve verificare. Non includere introduzioni del tipo "Verifica che" o "Assicura che".

Conserva i riferimenti ai ticket per questioni poco chiare in cui il ticket contiene dettagli aggiuntivi che non possono essere facilmente descritti nelle stringhe di documentazione o nei commenti. Includi il numero del ticket alla fine di una frase in questo modo:

def test_foo():
 """Una stringa di documentazione di prova ha questo aspetto (#123456)."""