Guide de style de code

Ce guide contient des informations et des lignes directrices pour l'écriture de code pour BeeWare.

Style de code

BeeWare suit la norme PEP 8 dans notre base de code, sauf que la longueur des lignes est passée de 79 à 88 caractères. Nous utilisons Ruff pour appliquer les conventions PEP 8 dans la mesure du possible. Lorsque vous validez votre code, pre-commit effectue des vérifications, notamment avec Ruff. Dans la mesure du possible, cela formatera automatiquement votre code afin de garantir qu'il respecte nos normes de formatage et de style. Vous pouvez configurer certains IDE pour qu'ils exécutent automatiquement Ruff lors de l'enregistrement, ce qui peut faciliter le processus.

Gardez à l'esprit que la partie la plus importante de la PEP 8 est la Section 0 : Une cohérence stupide est le hobgobelin des petits esprits. Il existe des situations où rester cohérent avec la PEP 8 n'a pas de sens, et il est important de comprendre que, le cas échéant, il est acceptable, et parfois préférable, d'écrire du code qui n'est pas conforme aux règles énumérées. Savoir quand être incohérent avec ces règles est aussi important que de maintenir la cohérence dans la plupart des situations.

Cela se manifeste notamment dans les conventions de nommage. Les bibliothèques BeeWare doivent souvent servir de passerelle vers d'autres langages. Lors de la création d'enveloppes pour d'autres langages, il est préférable (et parfois obligatoire) de respecter les conventions de nommage du langage cible plutôt que celles de Python. Par exemple, lors de l'appel ou de la référence à du code Java, les fonctions doivent respecter la convention Java qui privilégie mixedCase, plutôt que celle de la PEP 8 qui privilégie snake_case.

Nous suivons l'orthographe américaine pour les noms d'API, les variables, etc.

La PEP 8 comporte également quelques ajouts spécifiques à BeeWare :

Fractionnement des appels de fonction longs

Lorsqu'un appel de fonction comportant plusieurs arguments ne tient pas sur une seule ligne, placez chaque argument sur une ligne distincte en terminant le dernier argument par une virgule. Ruff autorise (et suggère) un format permettant de regrouper plusieurs arguments sur une seule ligne :

my_function(
    arg1, arg2, arg3
)

Il ne faut pas utiliser ce style. Il vaut mieux répartir les arguments sur plusieurs lignes en ajoutant une virgule à la fin du dernier argument :

my_function(
    arg1,
    arg2,
    arg3,
)

Fractionnement de longues chaînes de caractères

Lorsqu'un argument de type chaîne doit être réparti sur plusieurs lignes pour respecter les contraintes de longueur de ligne, placez les littéraux de chaîne concaténés entre parenthèses afin qu'il soit clair que la chaîne constitue un seul argument. En d'autres termes, nous préférons :

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

au-dessus de :

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

Ce qu'il faut éviter

Nous essayons d'éviter les modules utils autant que possible, tout en sachant qu'ils sont parfois inévitables. L'alternative préférée est de trouver la fonctionnalité ailleurs dans le code source, au lieu d'utiliser un module utils.

En règle générale, nous essayons d'éviter ou de différer tout code d'initialisation coûteux, afin d'accélérer le démarrage de l'application. Par exemple, les modules du paquet toga-core sont « chargés à la demande » : ils ne sont importés qu'une fois demandés, plutôt que tous d'un coup. Cela accélère le démarrage et ne consacre du temps qu'à ce que l'application utilise réellement.