Écrivez du code Python maintenable

Si vous devez vous repérez en montagne, vous aurez besoin d'une carte ! Et cette carte géographique doit être présentée de façon cohérente et fiable pour pouvoir être utilisée de façon efficace. C’est exactement la même chose pour les logiciels, qui doivent respecter des standards cohérents et fiables, afin d’être facilement lus et compris par vos collègues programmeurs.

De petits détails, comme le fait d’ordonner votre fichier de la façon attendue, ou de séparer les opérateurs avec les espacements standard, peuvent aider les lecteurs de votre code à se sentir un peu moins perdus, et à accomplir leur mission de programmation en cours avec le moins de frustration possible !

Mais bien sûr ! La PEP 8 a des avis sur tout, même sur des choses aussi banales que le fait de laisser ou non des espaces autour de vos signes « = »… Dans ce chapitre, nous allons nous pencher sur les aspects les plus importants de la mise en page de votre code Python.

Soyez cohérent avec l'indentation

En Python, vous pouvez utiliser soit des espaces, soit des tabulations, mais pas un mélange des deux. Du coup, il est recommandé d’utiliser 4 espaces, pour que les développeurs n’obtiennent pas d’erreurs d’« indentation inattendue » lorsqu’ils copient du code.

Utilisez des espaces

Voici deux blocs de code Python fonctionnellement identiques. Voyez combien de différences entre les deux vous arrivez à trouver ! (Il y en a au moins 12, en fonction de la façon dont vous comptez.)

# Bon code, selon la PEP 8.
def protect_animals(animals, sanctuary="little farm", max_places=4):
    """Place les animaux donnés dans un sanctuaire."""
    is_little = "little" in sanctuary
 
    if max_places < 5 or is_little:
        print("C'est petit, mais c'est mieux que rien !")
 
    protected = animals[:max_places]
    print(f"Nous avons protégés ces animaux : {protected}")
 
animals = ["cochon", "poule", "cerf", "lapin", "chien"]
protect_animals(animals)

# Mauvais code, selon la PEP 8.
def protect_animals(animals,sanctuary = "little farm",max_places = 4):
    is_little="little" in sanctuary
 
    if max_places<5 or(is_little):
        print( "C'est petit, mais c'est mieux que rien !" )
 
    protected=animals[ : max_places]
    print( f"Nous avons protégés ces animaux : { protected }" )
 
animals = [ "cochon","poule","cerf","lapin","chien" ]
protect_animals( animals )

Pour faire simple, si votre code ressemble au premier exemple, alors il est conforme à la PEP 8. S’il ressemble à certaines parties du deuxième exemple, alors il peut sembler peu esthétique et déroutant ! 👹

Voici quelques-unes des lignes directrices clés concernant les espaces. Vous trouverez des exemples pour chacune d’entre elles dans les exemples de code ci-dessus.

• Mettez un seul espace autour des opérateurs d’affectation (  is_little = "little" in sanctuary  ) et des opérateurs logiques (  max_places  < 5  ). La seule exception intervient lorsque l’on fixe des valeurs par défaut en paramètres de fonctions et méthodes, telles que  max_places=4  .

• Ne laissez jamais d’espaces tout de suite à l’intérieur de parenthèses ou de crochets. Écrivez  (expression)  et  [0]  , pas  ( expression )   ou  [ 0 ]  .

• Ne laissez pas de blanc entre une fonction, comme  print()  , et ses arguments.

• Laissez un espace entre  if  et toute parenthèse. La même règle s’applique à  for  . Ceci vise à être cohérent avec les situations où il n’y a pas de parenthèses.

Utilisez des sauts de ligne

Si vous pensiez que nous en avions fini avec les espacements, accrochez-vous encore un peu ! 😅  La PEP 8 a également des recommandations sur l’utilisation des sauts de ligne…

Oui – mais avec modération. Dans les livres, on saute des lignes entre les paragraphes, mais pas après chaque phrase. Appliquez le même principe au code Python – regroupez les lignes de code qui vont ensemble (un peu comme des paragraphes), mais en dehors de ce cas, ne sautez pas de ligne.

De plus, la PEP 8 recommande ce qui suit :

• Avant une définition de classe (c’est-à-dire quand vous écrivez  class MyClass  ) ou une définition de fonction (c’est-à-dire quand vous écrivez  def my_function(...):  ), sautez deux lignes.

• Avant une définition de méthode au sein d’une classe, ne sautez qu’une seule ligne.

Limitez la longueur des lignes

Certains développeurs utilisent une fenêtre étroite, et il est très peu commode de lire du code qui dépasse de l’écran (ou qui passe à la ligne).

C’est pourquoi la PEP 8 suggère de limiter les lignes de code à 79 caractères.

De nos jours, les développeurs sont plus susceptibles d’utiliser des éditeurs avec des fenêtres larges, donc cette règle est peut-être plus stricte que nécessaire.

Cette règle reste importante à suivre, car il s’avère que l’on parcourt plus facilement plusieurs lignes courtes qu’une seule ligne longue.

Écrivez des expressions sur plusieurs lignes

Utilisez plusieurs lignes pour l’expression ! Mais il vous faudra prendre quelques précautions…

Dans l’exemple suivant, il est difficile de voir que  parameter_number_3  est en fait un argument, car il apparaît sur la deuxième ligne, avec la même indentation que le code :

def function_with_a_rather_long_name(parameter_number_1, parameter_number_2,
    parameter_number_3):
    my_function(parameter_number_1)
    return parameter_number_2

La PEP 8 recommande les alternatives suivantes pour éviter cela :

# Aligne les paramètres sur la verticale
def function_with_a_rather_long_name(parameter_number_1, parameter_number_2,
                                     parameter_number_3):
    my_function(parameter_number_1)
    return parameter_number_2

# Même chose, mais avec un paramètre par ligne
def function_with_a_rather_long_name(parameter_number_1,
                                     parameter_number_2,
                                     parameter_number_3):
    my_function(parameter_number_1)
    return parameter_number_2

# Un paramètre par ligne, et la parenthèse au même niveau d’indentation que la fonction
def function_with_a_rather_long_name(
    parameter_number_1,
    parameter_number_2,
    Parameter_number_3
):
    my_function(parameter_number_1)
    return parameter_number_2

Notez que, dans chaque cas, on voit clairement au premier coup d’œil quelles parties du code correspondent respectivement aux arguments et au corps de la fonction. Problème résolu !

Enfin, voici une astuce élégante pour découper vos chaînes de caractères trop longues : utilisez une parenthèse, et insérez à l’intérieur plusieurs petites chaînes de caractères, séparées seulement d’un saut de ligne.

super_long_password = (
    "erfzfefrzvterbytnrezrtvbytyruetrgtrth"
    "zeergvzreafz'((-'eg'((yhvgbrz'trvytrh"
    "zerbetrtzbrtyezegbyebzrtbrebrtberbtrg"
    "zevrebtniukoy;i;yu,yt,trntehtrgegretr"
)

Lors de l'exécution du code, elles vont se « recoller » pour n’en former qu’une grande. 😉

Organisez vos fichiers

Que vous regardiez une carte lorsque vous êtes perdu en pleine nature, ou un module Python lorsque vous êtes perdu dans vos pensées, il vous sera utile de savoir où trouver les choses sur votre page.

Bien sûr, la PEP 8 a un ordre recommandé pour vos fichiers Python !

1. Les commentaires qui concernent la totalité du fichier vont en haut.

2. Les imports suivent cet ordre :

   1. Modules de la bibliothèque standard, par exemple  import random  .

   2. Modules de bibliothèques tierces, par exemple  import sklearn  .

   3. Modules locaux, par exemple  import mymodule  .

3. Les constantes, par exemple  MY_CONSTANT = 77  .

4. Tout autre code.

En résumé

• Pour que le code Python soit cohérent et facile à lire, la PEP a différentes recommandations sur la présentation du code.

• Le code doit être indenté avec 4 espaces (et non des tabulations).

• Le code doit utiliser des espaces et sauts de lignes adaptés pour aérer le code sans trop le gonfler.

• Les lignes de code ne doivent pas excéder 79 caractères, et il faut être prudent si l’on découpe de longues expressions en plusieurs lignes.

• Les fichiers doivent être écrits en commençant par les commentaires qui concernent le fichier, puis les imports, puis les constantes, et ensuite tout le reste du code.

Eh bien, tout cela balaie comment écrire du code Python lisible ! Au prochain chapitre, nous irons plus loin, et nous suivrons les conseils de la PEP 8 pour écrire du code antibug !