Bonjour à tous,
Aujourd’hui je vais vous donner 12 bonnes pratiques pour vous aider à développer vos outils. Les astuces partagées vous permettront d’adopter un style de programmation qui est lisible et facilement compréhensible par tout le monde, y compris vous-même. En effet, il n’y a rien de pire que de se replonger dans un code et de devoir tout décortiquer à nouveau alors que c’est vous qui l’avez développé.
Ces recommandations sont issues de l’expérience et de différentes normes comme la PEP 8 (Python Enhancement Proposals). J’ai délibéré utilisé le mot « norme » pour pousser le trait. Ces recommandations sont à suivre car elles sont validées et adoptées par des experts. Si ces personnes passent du temps à réfléchir sur ces sujets, cela ne doit pas être pour rien.
D’autres conseils proviennent du retour d’expérience de plusieurs projets et de mes différentes recherches sur le sujet. Bonne lecture !
1. L’indentation
Pour l’indentation, il est recommandé d’utiliser 4 espaces par niveau, ni plus, ni moins, pas de tabulation. Cette dernière est à éviter sauf si vous avez réglé votre logiciel de développement pour insérer 4 espaces pour une tabulation.
Lorsque la ligne de code est trop longue, il est nécessaire de faire des retours à la ligne. Dans ce cas, on revient à la verticale la parenthèse ou autre symbole ouvrant. Lorsque vous devez revenir à la ligne lors de la définition d’une fonction, il faut ajouter une indentation pour différencier les arguments du corps de la fonction.
Lors de l’appel de fonction, s’il faut revenir à la ligne, rajoutez une indentation et pas d’argument après la parenthèse ouvrante. Voici les exemples donnés dans la PEP 8.
# Correct:
# Le retour à la ligne est aligné sur la parenthèse ouvrante.
foo = long_function_name(var_one, var_two,
var_three, var_four)
# Directement après la parenthèse ouvrante, on revient à la ligne et on ajoute 4 espaces
# (un niveau d'indentation de plus) pour distinguer les arguments du corps de la fonction
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
# Dans le corps du programme, si on revient directement à la ligne, il faut rajouter une indentation
# pour différencier les arguments du reste du code. Pas d'argument sur la première ligne.
foo = long_function_name(
var_one, var_two,
var_three, var_four)
# Incorrect:
# Pas d'argument sur la première ligne lorsqu'on revient à la ligne dans le corps du code.
# Il aurait fallu s'aligner sur la parenthèse ouvrante par exemple.
foo = long_function_name(var_one, var_two,
var_three, var_four)
# Une indentation supplémentaire aurait dû être faite ici pour distinguer les arguments du corps
# de la fonction.
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)2. Règles de nommage
Les noms de variables, de fonction et de modules doivent être en minuscules exclusivement. Les mots sont séparés par un « underscore » ou « tiret du bas » ou encore « tiret du 8 » :).
variable_super
fonction_geniale()
module_chouetteLes constantes doivent être écrites en majuscules uniquement.
CONSTANTE_UTILE
NOMBRE_AVOGADROLes classes et les exceptions prennent une majuscule sur le premier caractère de chaque mot. Chaque mot est collé, il n’y a pas de séparation.
ClasseVoiture
ExceptionValeur
Chaque nom donné doit avoir du sens. Il faut rester simple. On peut utiliser la combinaison entre le nom d’une fonction et ses arguments.
def fabriquer_pain(ingredients: object) -> object:3. Longueur maximale des lignes
Si d’aventures vous êtes amené à imprimer du code, il est conseillé de ne pas dépasser 79 caractères sur une ligne. Si votre ligne de code dépasse cette valeur, référez-vous au point 1. Cette limite permet également d’avoir plusieurs documents côte à côte et de pouvoir les lire sans avoir à dérouler horizontalement le fichier.
La plupart des environnements de développement de code donne la possibilité d’afficher une ligne verticale pour matérialiser cette limite. Il suffit de rentrer le nombre de caractères souhaité.
4. Gestion des espaces
Il est recommandé d’entourer les opérateurs par un espace pour accroître la lisibilité. Quand on dit opérateur, voici quelques exemples : +, -, / ,* ,==, !=, <=, not, in, and, or, …
# correct:
ma_variable = 10 + 9
ma_chaine = "voiture"
ma_chaine == ma_variable
# incorrect:
ma_variable=10+9
ma_chaine ="voiture"
ma_chaine== ma_variableOn évitera les espaces entre crochets, parenthèses et accolades.
# correct:
ma_liste[1]
mon_dico{"clé"}
ma_fonction(argument)
# incorrect:
ma_liste[ 1 ]
mon_dico{"clé" }
ma_fonction( argument )Lors de l’utilisation des virgules et deux points « : », on ne mettra pas d’espace avant mais un après. Cependant il existe une exception lorsqu’on utilise les plages avec les indices. Il n’y aura pas d’espace dans ce cas-là.
# correct :
ma_liste = [1, 2, 3, 4]
mon_dico = {'clé1': 'Valeur1', 'clé2': 'Valeur2'}
ma_fonction(arg1, arg2)
ma_liste[:2]
ma_liste[1:2]
# incorrect
ma_liste = [ 1 , 2 , 3 , 4]
mon_dico = {'clé1' : 'Valeur1' , 'clé2' : 'Valeur2'}
ma_fonction(arg1 ,arg2)
ma_liste[: 2]
ma_liste[1 : 2]5. Les commentaires
N’hésitez pas à abuser des commentaires. Ils permettent de mieux comprendre votre code, pour vous comme pour les autres. Au moment où vous écrivez votre code, tout va bien. Mais dans quelques mois, vous serez bien content d’avoir mis des commentaires pour reprendre le fil.
Les commentaires sont précédés du symbole « # ». Taper ce symbole au clavier est un peu fastidieux surtout si vous voulez bien commenter votre code. Les éditeurs de texte propose des raccourcis pour mettre une ligne en commentaire. Si celui-ci n’est pas défini par défaut, en allant fouiller dans les paramètres, vous trouverez certainement comment configurer un nouveau raccourci. Personnellement, j’utilise CTRL+Q.
Votre commentaire doit être sur le même niveau d’indentation que la ligne commentée. Les commentaires qui suivent le code doivent être évités au possible et seront séparés par au moins deux espaces.
# Création de ma variable.
ma_variable = 123
ma_varible = 200 # Changement de valeur de ma variable.6. Guillemets ou apostrophes pour les chaînes de caractères ?
J’en parle dans l’article dédié aux chaînes de caractères. La PEP 8 ne donne pas de préconisation figée dans le marbre. Choisissez un type et gardez-le pour avoir un code cohérent. Dans le cas où vous devriez utiliser le backslash, passez de l’un à l’autre pour éviter ce symbole. Il nuit à la lisibilité.
7. Vous développez un outil pour les autres ?
Discutez avec les futurs utilisateurs. Faites leur essayer une première version pour avoir leur retour. Notez tous les bugs et tous les problèmes qu’ils peuvent avoir. Toutes les informations que vous pourrez récupérer sont une mine d’or. La mise en place de leurs doléance ne sera pas forcément aisée mais si vous prenez en compte les erreurs potentielles que feront les utilisateurs, cela vous évitera des heures d’explication.
Pour un projet d’automatisation pour la création d’un diagramme de flux, j’ai créé toute une séquence du code qui ne fait que vérifier les données rentrées par l’utilisateur. Cela m’a pris un peu de temps et plusieurs versions pour prendre en compte tous les problèmes. Au final, lorsque l’utilisateur se trompe, au lieu d’avoir une erreur Python, qu’il ne connait pas forcément, il a un message personnalisé qui le guide dans la résolution de son erreur. Cela vous permet d’avoir la paix une fois l’outil déployé.
8. Faites des fonctions simples
Il est très important de faire des fonction simples qui ne font qu’une seule tâche. Si une fonction commence à être trop complexe, réfléchissez si elle ne peut pas être découpée en plusieurs. Le nombre d’arguments doit être réduit au maximum. La complexité d’une fonction se mesure au nombre d’arguments qu’elle appelle.
Une fonction simple est plus facile à tester et à maintenir si vous devez la faire évoluer. Je vous conseille fortement de garder vos fichiers qui permettent de tester vos fonctions. Si vous vous reposez une question plus tard, vous aurez juste à relancer votre fichier. Personnellement, je crée un dossier « tests » dans lequel je range mes fichiers.
Prenez une minute pour documenter la fonction. Le PEP 257 donne des préconisations pour la création d’une en-tête dans les fonctions. C’est ce qu’on appelle « docstring ». Je vous ai mis deux exemples issus de la documentation PEP. L’idée est à minima de faire une ligne permettant de dire ce que fait la fonction.
def function(a, b):
"""Do X and return a list."""
def foo():
"""
This is the second line of the docstring.
"""Je me permets un dernier point sur les fonctions. Ayez le réflex de vous dire que si vous faites passer une variable booléenne dans votre fonction, c’est que celle-ci peut être divisée en deux :). Suivant votre booléen, vous appellerez alors l’une ou l’autre fonction.
9. Ecrivez les grandes étapes sur une feuille !
Le papier n’est pas mort ! Ni le tableau blanc ! Lorsque que votre programme commence à être conséquent, il peut être très utile de mettre à plat toute la structure de celui-ci. En effet, réfléchir en amont sur ce que vous allez faire permet d’anticiper les liens entre les modules, les fonctions, … En faisant ici, si vous êtes plusieurs à travailler sur le sujet, vous pourrez vous partager les tâches. Il faut juste bien définir les interfaces afin de savoir quels sont les arguments que vous passerez.
10. Des noms de variables et fonctions optimisés
Des noms de variables, de fonctions pertinents limites le nombre de commentaires.
11. Informez-vous sur les librairies existantes
Faites des recherches sur les librairies disponibles. Comme on dit, ça ne sert à rien de réinventer l’eau tiède ! Il y a énormément de librairies disponibles en Python. Il est fort possible que l’une d’entre elles puisse vous aider. Si ce n’est pas le cas, vous avez gagné un projet supplémentaire 🙂
12. Testez et gardez la trace de vos tests
Comme mentionné dans la section sur les fonctions, il faut tester votre code et garder vos scripts de tests. Il n’y a rien de plus frustrant que de se demander à nouveau si une fonction ou une partie de votre programme fonctionne correctement ou non. Si vous avez encore les fichiers tests, il vous sera rapide de vérifier ce point.
Merci de m’avoir lu ! N’hésitez pas à laisser un commentaire !
A bientôt,
Benjamin
Article très intéressant surtout quand on débute pour avoir les règles de bonne pratique et éviter de faire un code illisible.
A lire absolument !