Introduction

Chaque personne qui code a son propre style et ses propres habitudes. Mais, si vous travaillez en équipe, ou si vous devez partager avec d'autres développeurs, votre code doit être lisible. C'est une bonne habitude à prendre, même lorsque l'on code pour soi-même. PEP8 (alias PEP-8, alias PEP 8) signifie Python Enhancement Proposals. Les créateurs du langage Python, Guido van Rossum, Barry Warsaw et Nick Coghlan, l'ont conçu comme un guide de style documenté pour aider les développeurs Python à écrire du code lisible. Dans cette quête, nous allons passer en revue quelques bonnes pratiques majeures.

Requis

Pour ce cours, il faudra passer par un IDE de type Visual Studio Code ou PyCharm (ou autres...).

Objectifs

✅ comprendre le raisonnement qui sous-tend les recommandations du PEP 8 ✅ connaître certaines des principales bonnes pratiques pour écrire des codes lisibles

Sommaire

Contenu de la quête:

• Fonctions et noms de variable
• Indentation
• Longueur de lignes
• Rupture de ligne et opérateurs
• Espace

Fonctions et noms de variables

Les noms de fonction doivent être en minuscules, les mots étant séparés par des traits de soulignement si nécessaire pour améliorer la lisibilité. Les noms de variables suivent la même convention que les noms de fonctions. La casse mixte n'est autorisée que dans les contextes où c'est déjà le style dominant (par exemple, threading.py), pour conserver la compatibilité ascendante. Dans tous les cas, s'il est nécessaire de le mentionner, n'utilisez PAS de mots protégés, c'est-à-dire des mots utilisés par le langage lui-même tels que list, dict, ou str Évitez également de nommer vos variables avec une seule lettre ou un seul chiffre. Gardez à l'esprit que certaines lettres peuvent parfois prêter à confusion. C'est le cas de la lettre "O" qui peut être confondue avec le chiffre 0 ; de la majuscule i ("I") et de la minuscule "L" ("l") qui ont exactement la même apparence ; et toutes deux peuvent être confondues avec le chiffre "1". Évitez-les chaque fois que vous sentez que la différence peut être moins que claire pour un autre développeur.

Pour en savoir plus: Conventions de dénomination normatives

Indentation

En Python, si l'indentation d'un bloc d'instructions (fonction, instruction conditionnelle, boucle...) n'est pas correcte, vous obtiendrez une erreur. Mais au-delà d'une indentation correcte, il y a quelques lignes directrices à suivre lorsque l'on veut s'assurer que le code indenté est facile à lire lorsque l'on a plus d'un argument dans une fonction donnée.

La règle est d'utiliser 4 espaces par niveau d'indentation.

Les lignes de continuation doivent aligner les éléments enveloppés soit verticalement en utilisant la jonction de ligne implicite de Python à l'intérieur des parenthèses, des crochets et des accolades, soit en utilisant une indentation suspendue.

L'indentation suspendue est un style de composition où toutes les lignes d'un paragraphe sont indentées sauf la première. Dans le contexte de Python, le terme est utilisé pour décrire un style où la parenthèse d'ouverture d'une déclaration entre parenthèses est le dernier caractère non espace de la ligne, les lignes suivantes étant indentées jusqu'à la parenthèse de fermeture.

Lors de l'utilisation d'une indentation suspendue, il convient de prendre en compte les éléments suivants : il ne doit pas y avoir d'arguments sur la première ligne et une indentation supplémentaire doit être utilisée pour se distinguer clairement comme une ligne de continuation :

# Correct:

# Aligné sur le délimiteur d'ouverture.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Ajoutez 4 espaces (un niveau supplémentaire d'indentation) pour distinguer les arguments du reste.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Les tirettes suspendues doivent ajouter un niveau.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# Faux

# Arguments sur la première ligne interdits lorsque l'alignement vertical n'est pas utilisé.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Une mise en retrait supplémentaire est nécessaire car l'indentation ne se distingue pas.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Lire la suite : Indentation

La longueur de la ligne

L'enveloppement par défaut dans la plupart des outils perturbe la structure visuelle du code, ce qui le rend plus difficile à comprendre. Les limites sont choisies pour éviter l'enveloppement dans les éditeurs dont la largeur de fenêtre est réglée sur 80, même si l'outil place un glyphe marqueur dans la dernière colonne lors de l'enveloppement des lignes. Il se peut que certains outils Web ne proposent pas du tout d'habillage dynamique des lignes.

C'est pourquoi la longueur maximale recommandée est de 79 caractères.

En savoir plus : Longueur maximale des lignes

Cassures de ligne et opérateurs

Pendant des décennies, le style recommandé était de faire une pause après les opérateurs binaires. Mais cela peut nuire à la lisibilité de deux manières : les opérateurs ont tendance à être dispersés sur différentes colonnes de l'écran, et chaque opérateur est éloigné de son opérande et placé sur la ligne précédente. Dans ce cas, l'œil doit faire un travail supplémentaire pour savoir quels éléments sont ajoutés et lesquels sont soustraits :

# Faux:
# les opérateurs sont éloignés de leurs opérandes
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

Pour résoudre ce problème de lisibilité, les mathématiciens et leurs éditeurs suivent la convention inverse. Suivre la tradition des mathématiques permet généralement d'obtenir un code plus lisible :

# Vrai
# facile de faire correspondre les opérateurs avec les opérandes
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

Lire la suite : Faut-il un saut de ligne avant ou après un opérateur binaire ?

Whitespace

Le Writespace apporte un peu d'air à vos lignes de code et peut contribuer à améliorer leur lisibilité... ou sérieusement les handicaper lorsqu'il n'est pas fait correctement. Voici les principales bonnes pratiques pour l'obtenir correctement.

Évitez les espaces superflus dans les situations suivantes :

1. immédiatement à l'intérieur des parenthèses, des crochets ou des accolades
2. Entre une virgule de fin et une parenthèse fermée qui suit
3. Immédiatement avant une virgule, un point-virgule ou deux-points1.
4. Toutefois, dans une tranche, les deux-points agissent comme un opérateur binaire et doivent avoir une quantité égale de chaque côté. Dans une tranche étendue, les deux points-virgules doivent avoir la même quantité d'espacement. Exception : lorsqu'un paramètre de tranche est omis, l'espace est omis.
5. immédiatement avant la parenthèse ouverte qui commence la liste des arguments d'un appel de fonction
6. Immédiatement avant la parenthèse ouverte qui commence une indexation ou un découpage en tranches.
7. Plus d'un espace autour d'un opérateur d'affectation (ou autre) pour l'aligner sur un autre opérateur.

# Correct:
#1
spam(ham[1], {eggs: 2})

#2
foo = (0,)

#3
if x == 4: print x, y; x, y = y, x

#4
ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
ham[lower:upper], ham[lower:upper:], ham[lower::step]
ham[lower+offset : upper+offset]
ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
ham[lower + offset : upper + offset]

#5
spam(1)

#6
dct['key'] = lst[index]

#7
x = 1
y = 2
long_variable = 3

# Faux:
#1
spam( ham[ 1 ], { eggs: 2 } )

#2
bar = (0, )

#3
if x == 4 : print x , y ; x , y = y , x

#4
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]

#5
spam (1)

#6
dct ['key'] = lst [index]

#7
x             = 1
y             = 2
long_variable = 3

Pour en savoir plus: Espaces dans les expressions et les déclarations

Automatisation de la vérification des directives PEP 8

Il existe différents outils permettant de vérifier que les règles PEP 8 ont été correctement suivies par le développeur. L'un d'eux est l'utilitaire Flake8.

Pour installer Flake8 : pip install flake8

Pour vérifier un fichier : flake8 <myfile.py>

Pour vérifier un ensemble de fichiers dans un dossier : flake8 <path_to_my_folder>

En résumé

La lisibilité est essentielle dans le codage pour optimiser la collaboration avec d'autres développeurs, la maintenance de notre propre code et réduire les risques de générer des bogues et des erreurs à partir d'un code mal écrit. Le PEP 8 (Python Enhancement Proposal) a été publié par les créateurs de Python pour aider les développeurs à écrire du code qui soit beau et facile à lire et à comprendre. Cela inclut, par exemple, des directives concernant la convention de dénomination des variables et des fonctions, l'indentation, la longueur des lignes, les freins de ligne et le placement des opérateurs, ainsi que les espaces blancs. Il est recommandé de lire les directives détaillées pour chaque sujet et de jeter un coup d'œil à l'ensemble du document au moins une fois. Cependant, vous pouvez obtenir de l'aide pour automatiser la vérification des directives à l'aide de librairies utilitaires Python comme Flake 8.

Challenge

Faites une copie d'un de vos notebooks ou google colabs. Corrigez toutes les violations des directives PEP 8 que vous pouvez identifier. Ensuite, vérifiez votre nouveau code avec Flake 8. Procédez aux corrections restantes signalées par l'utilitaire. Soumettez le lien vers votre nouveau code dans la quête.

Critères d'acceptation

• [ ] Soumettez un lien accessible vers votre notebook ou google colab
• [ ] Aucune violation des lignes directrices signalée par Flake 8
• [ ] Vérifiez le code de vos collègues en utilisant Flake 8