Comment configurer une norme de programmation Python et s’y tenir

Qu’est-ce que la PEP 8 ?

PEP est l’acronyme de Python Enhancement Proposal, ou proposition d’amélioration de Python. Il s’agit d’un guide de style sur les lignes directrices et les meilleures pratiques en matière de programmation Python. La PEP 0 a été rédigée en 2001 par Guido Van Rossum, Barry Warsaw et Alyssa Coghlan. Les numéros PEP sont attribués par les contributeurs et, au fil du temps, de nouvelles PEP ont été publiées avec des normes de style et de conception Python recommandées.

La PEP 8 assure la cohérence de la structure et de la conception du code. La cohérence est un enjeu pour l’ensemble des projets, ainsi que pour les modules et fonctions individuels. Plus le code est cohérent, plus il est lisible pour l’ensemble des développeurs.

Les normes de formatage de base pour Python

PEP 8 indique plusieurs normes communes au sein de Python. Les normes comportent également des exceptions, il convient donc de faire preuve de créativité lorsque cela s’avère nécessaire. Pour commencer à suivre les meilleures pratiques de programmation Python, concentrez-vous sur les conventions de nommage, l’indentation et les commentaires.

Les conventions de nommage

La bibliothèque de conventions de nommage de Python s’applique aux éléments de l’architecture du code auxquels les développeurs attribuent des noms. Rédigez tous les nouveaux noms de modules et de paquets conformément aux normes suivantes afin de garantir la cohérence et la lisibilité du code :

Suivre un principe primordial pour tous les noms. Créer des noms basés sur l’utilisation, plutôt que sur la fonction exécutée par le code. Utiliser des noms descriptifs.

Les options courantes de convention de nommage en Python sont les suivantes :

• Il est possible d’utiliser une seule lettre minuscule ou une seule lettre majuscule dans le nom. Par exemple, utilisez p ou P.
• Tout le texte peut être écrit en minuscules. Par exemple, il convient d’écrire class file de cette manière : classfile.
• Il existe la convention « Snake Case », dans laquelle tout le texte est en minuscules et les mots séparés par un trait de soulignement (underscore). Par exemple, class_file_open.
• Tout le texte peut être rédigé en majuscules. Dans cet exemple, class file devient CLASSFILE.
• Une variante de Snake Case consiste à mettre le texte en majuscules et à séparer les mots par un trait de soulignement : CLASS_FILE_OPEN.
• Les styles CapWords ou CamelCase figurent la première lettre de chaque mot du nom en majuscule. Un exemple : ClassFileOpen.
• Avec MixedCase, le nom commence par une lettre minuscule et le mot suivant du nom commence par une lettre majuscule. Dans le cas présent, cela donnerait classFileOpen.
• Chaque mot peut être en majuscule et séparé par des traits de soulignement. Cette combinaison de casses CamelCase et Snake case se présente comme suit : Class_File_Open.

Les conventions de nommage peuvent également utiliser un underscore pour des raisons de cohérence de formatage. Voici les approches les plus courantes :

• Un seul trait de soulignement à la fin : un seul underscore à la fin_.
• Un double trait de soulignement avant le nom : __boo move -.
• Un double trait de soulignement initial et final : __boo move__.

Ces conventions de formatage peuvent prêter à confusion dans certains cas, lorsque les lettres ressemblent aux nombres entiers 1 et 0. Évitez ces caractères d’appellation et ce formatage dans la mesure du possible :

• L minuscule (l).
• I majuscule (comme dans Ignorer).
• O majuscule (comme dans Oh).

Par ailleurs, tous les identificateurs utilisés dans une bibliothèque standard doivent être compatibles avec le standard d’encodage de caractères ASCII.

Il faut également prendre en compte les conventions de nommage suivantes :

• Les recommandations présentes dans la documentation Python concernant les noms de paquets et de modules mettent l’accent sur des noms courts, en minuscules, en s’appuyant sur d’autres caractères lorsque cela est nécessaire pour la lisibilité. L’utilisation des underscores pour ces noms est généralement déconseillée.
• Pour les noms de classes, utilisez la méthode CamelCase. Utilisez toutes les lettres minuscules séparées par des traits de soulignement, comme pour les fonctions, lorsqu’il s’agit d’une interface appelable.
• Pour les noms de variables, les meilleures pratiques de mise en forme imposent des noms de types courts en CamelCase. Ajoutez _co pour déclarer un comportement covariant. Ajoutez _contra pour déclarer un comportement contravariant.
• Les variables globales ne sont utilisées que dans un seul module. Le __xxx__ précédé et suivi d’un double trait de soulignement indique qu’il s’agit d’une variable globale.
• Les noms de fonctions doivent apparaître soit en minuscules et en Snake Case, si cela améliore la lisibilité, soit dans le style mixedCase, si cela est nécessaire pour conserver la compatibilité ascendante.
• Au niveau du module, les constantes doivent être nommées en majuscules et en Snake Case, avec des traits de soulignement entre chaque mot.
• Les conventions de dénomination peuvent indiquer si une interface est publique ou interne. Utilisez l’attribut __all__ pour indiquer qu’une API est privée ou non publique.

Enfin, il faut penser à l’existant lors de l’attribution de noms en Python.

• N’utilisez pas d’underscore en tête.
• Si un nom public entre en conflit avec un mot-clé réservé, ajoutez un seul trait de soulignement à la fin du nom.
• Pour les attributs de données publiques, ne nommez que l’attribut.
• Si une classe doit être sous-classée, nommez les attributs que vous ne voulez pas voir sous-classés avec un double underscore.

L’indentation

Python utilise quatre espaces pour chaque niveau d’indentation. Pour les lignes de continuation, enveloppez les éléments verticalement en utilisant la jonction de lignes Python à l’intérieur de parenthèses, de crochets ou d’accolades en utilisant un retrait suspendu. Avec un retrait suspendu, n’utilisez pas d’arguments sur la première ligne et utilisez une indentation secondaire pour distinguer une ligne de continuation.

# Correct:

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

(Crédit : PEP 8 Style Guide for Python Code)

Si la partie conditionnelle d’une instruction if occupe plusieurs lignes, utilisez un mot-clé de deux caractères plus un espace, et ajoutez une parenthèse ouvrante pour créer un retrait de quatre espaces.

# No extra indentation.
if (this_is_one_thing and
    that_is_another_thing) :
    do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing) :
    # Since both conditions are true, we can frobnicate.
    do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing) :
    do_something()

(Crédit : PEP 8 Style Guide for Python Code)

Les commentaires

Les développeurs pourraient qualifier les commentaires de mal nécessaire. Ils sont essentiels pour construire une base de code compréhensible par les membres présents et futurs d’une équipe. Les commentaires doivent être formés de phrases complètes. Relisez vos commentaires pour vous assurer qu’ils sont clairs et compréhensibles. Demandez à un autre développeur d’interpréter les commentaires. A-t-il bien compris ce que vous vouliez dire ? Si ce n’est pas le cas, modifiez les commentaires.

Les commentaires doivent être à jour. Si vous modifiez le code, mettez à jour les commentaires pour qu’ils correspondent à la fonction actuelle du code. Pour suivre le guide PEP-8, écrivez les commentaires du code Python en anglais. Le choix d’une seule langue pour les commentaires garantit sa portabilité.

Python prend en charge plusieurs types de commentaires, en fonction de la structure du code. Utilisez des blocs de commentaires indentés de la même manière que le code. Ajoutez un # suivi d’un espace pour commencer le texte du commentaire. Séparez les paragraphes d’un commentaire à l’aide d’un seul #. Si cela s’avère utile, utilisez des commentaires en ligne. Ces commentaires apparaissent sur la même ligne que le code. Séparez les commentaires en ligne de l’instruction de code par deux espaces. Commencez le commentaire en ligne par un # et un seul espace.

Les autres normes de programmation courantes avec Python

Les développeurs qui écrivent du code Python doivent consulter la PEP-8 et ses mises à jour pour se tenir au courant. Voici une brève liste des normes de programmation Python les plus répandues :

• Évitez tout espace blanc à la fin du code.
• N’utilisez pas le caractère backslash avec un espace pour indiquer une nouvelle ligne.
• Entourez les opérateurs binaires suivants d’un espace simple de chaque côté : =, <, >, !=, <>, <=, >=, in, not in, is, is not, and or not.
• Utilisez des guillemets simples ou des guillemets doubles pour les chaînes de caractères dans toute la base de données. Ne mélangez pas les deux. Pour les chaînes à trois guillemets, utilisez toujours des guillemets doubles.
• Utilisez deux lignes vierges pour entourer les définitions de fonctions et de classes de premier niveau.
• Utilisez des lignes vides à l’intérieur des fonctions pour séparer les sections logiques.
• Utilisez des caractères non ASCII uniquement lorsque cela est nécessaire pour indiquer des noms de lieux et de personnes.
• N’utilisez que des identificateurs ASCII en anglais.
• Les espaces sont utilisés pour les indentations, pas les tabulations. Ne les mélangez pas.
• Limitez toutes les lignes à un maximum de 79 caractères.

N.D.L.R. : Depuis la version 3 de Python, le langage exploite par défaut l’encodage UTF-8, mais bon nombre de conventions de nommage ont été pensé avant l’adoption de ce standard par le projet open source. Parce qu’il prend en charge l’UTF-8, Python 3 (et les versions ultérieures) demeure compatible avec l’encodage ASCII, la norme par défaut jusqu’à la fin de Python 2.x. Le fait de déconseiller de mettre des accents dans les noms des variables ou des classes (entre autres) vise, aussi, à s’assurer de la cohérence du code et de sa lisibilité. Attention, donc à configurer son éditeur de code ou son IDE spécifiquement pour UTF-8.

Comment les équipes font-elles respecter les normes de programmation ?

L’application de norme de programmation n’est pas aisée. Néanmoins, la lisibilité et la cohérence du code sont des pierres angulaires du langage Python et, pour y parvenir, les développeurs doivent respecter les normes.

Les équipes de développement qui les mettent en œuvre et les appliquent sont souvent plus productives que celles qui travaillent selon des styles et des préférences individuelles. Ne rendez pas la tâche plus laborieuse que nécessaire. Un code cohérent et lisible, basé sur des normes établies, permet à tout le monde de gagner du temps et d’éviter les frustrations. En outre, cela permet d’éviter les bugs longs à détecter, à dépanner et à résoudre en raison de pratiques individualistes et non standard.

Les équipes de développement doivent établir des normes de programmation Python qui conviennent à l’organisation et à l’équipe. Les responsables doivent commencer par une discussion ou une série de discussions consacrées à ce thème. Déterminez les points de désaccord entre les membres de l’équipe. Prenez le temps de créer une nomenclature en utilisant les normes Python. Les développeurs sont plus enclins à suivre les décisions qui sont transparentes et qui tiennent compte de leurs suggestions.

Au cours des revues de code et d’autres discussions, soyez à l’écoute des incohérences ou du manque de respect des normes. Si vous constatez que les développeurs ne les respectent pas, au détriment de la productivité et de la cohésion de l’équipe, organisez immédiatement une discussion en tête-à-tête. Ne laissez pas la qualité du code en pâtir avant d’agir.

C’est pourquoi il convient d’impliquer l’équipe dans toutes les mises à jour des normes de programmation et du guide de style Python, afin de garantir son accord et la transparence de son travail.

Bien que la cohérence du code soit importante, il arrive que les développeurs Python choisissent d’enfreindre les normes PEP 8. Dans certains cas, les guides de style et les normes compliquent la base de code au lieu de la rendre plus lisible. Les contributeurs au langage de programmation ont tout prévu : la PEP 8 encourage les développeurs à aller à l’encontre des normes Python lorsqu’elles rendent le code moins lisible, cassent des modules plus anciens ou empêchent le code d’être rétrocompatible.