VI) Les bonnes pratiques

1) Pourquoi avoir de bonnes pratiques

On code au début pour soi. Mais très vite, on va réutiliser du code écrit par d'autres, on va travailler en équipes. On peut aussi tout simplement avoir besoin de reprendre un code écrit il y a bien longtemps.

Pour toutes ses raisons, il faut avoir en tête de rester quelques points :

avoir une présentation claire ;
bien choisir ses noms de variables, de fonctions ;
documenter son code ;
y mettre des garde-fous pour faciliter sa conception, sa mise au point.

2) Norme de présentation

Python définit régulièrement des normes de programmation connues sous le nom de PEP (Python Enhancement Proposals).

Voici quelques points à respecter autant que possible.

Choisir une langue pour les noms de variables et la documentation et s'y tenir. En sciences, c'est souvent l'anglais.
Pour indenter, choisir de préférences 4 espaces. En bas de son éditeur, on peut souvent le faire.
Respecter les règles des noms :
- variables et fonctions en minuscules ( cpt, ma_fonction, ...) ;
- constantes en majuscules ( V_MAX, NB_VAL, ...);
- classe commençant par une majuscule (Personne, Tableau, ...)
Mettre un espace autour des opérateurs ( a = a + 1).

Des sites en ligne permettent de vérifier la présentation. Par exemple, allez voir https://www.pythonchecker.com/.

3) Les commentaires

Afin de rendre votre programme plus clair, il est nécessaire, dès que votre code dépasse une dizaine de lignes, d'introduire des commentaires. Bien sûr, cela peut permettre à une personne qui n'a pas écrit le programme de comprendre ce que vous avez voulu faire, mais cela peut aussi vous permettre, quelques mois après avoir terminé d'écrire votre code, de vous "rafraîchir la mémoire".

En Python, toute ligne commençant par le caractère dièse (#) sera considérée comme un commentaire par le système interpréteur/compilateur.

Voici un exemple de programme commenté :

def multiplication(a, b):
    res = 0
    # on boucle a fois
    while a>0:
        #on ajoute b à res
        res = res + b
        #on décrémente a
        a = a - 1
    return res
# La variable x est égale à la valeur renvoyée par la fonction multiplication pour a = 5 et b = 3
x = multiplication(5,3)
# on affiche la valeur de x
print(x)

Attention, dans l'exemple ci-dessus j'ai volontairement alourdi le programme avec des commentaires inutiles vu la simplicité de ce dernier.

4) La documentation d'une fonction

Toujours dans l'idée de rendre vos programmes plus clairs, il est important de proposer une documentation pour vos fonctions. Cette documentation doit donner des informations sur le comportement de votre fonction, plus précisément, votre documentation doit :

décrire votre fonction
donner le type des paramètres de votre fonction
donner le type de la valeur renvoyée par votre fonction

La documentation doit se trouver au tout début de votre fonction, elle commence par 3 guillemets """ et se termine aussi par 3 guillemets. Il est possible d'utiliser plusieurs lignes. Voici un exemple avec la fonction multiplication :

def multiplication(a, b):
    """Cette fonction multiplie 2 nombres a et b sans utiliser l'opérateur *
    - les paramètres sont a et b, tous les 2 de type number (int ou float)
    - la valeur renvoyée par la fonction est aussi de type number (int ou float)
    """
    res = 0
    while a>0:
        res = res + b
        a = a - 1
    return res

On utilise le terme de docstring pour désigner cette façon de rédiger la documentation d'une fonction (on rédige la documentation sous forme de docstring).

5) Les garde-fous

Dans une fonction, on utilise souvent des paramètres. le concepteur a une idée précise du type envisagé (entier, tableau, ...) mais Python étant un langage non type, rien ne limite que la fonction soit utiliser par erreur dans un autre cadre : par exemple, qu'une chaîne de caractère interviennent au lieu d'un entier.

Certaines fois, ces erreurs sont faciles à détecter mais dans d'autres cas, le comportement est étrange. Cela rend difficile la mise au point.

Voici un petit exemple :

def addition(a, b):
    """Cette fonction sans intérêt qui est pensée pour ajouter deux entiers."""
    res = a + b
    return res

On peut annoter simplement dans le code les types des entrées et des sorties. mais attention, ceci n'est pas un moyen de vérification.

def addition(a : int, b : int) -> int :
    """Cette fonction sans intérêt qui est pensée pour ajouter deux entiers."""
    res = a + b
    return res

L'inconvénient est qu'elle ne teste pas la nature des paramètres a et b.

Ainsi addition("2","3") va renvoyer "23". Python n'a pas détecté d'erreur.

Un moyen d'y remédier est d'utiliser des assertions :

def addition(a, b):
    """Cette fonction sans intérêt qui est pensée pour ajouter deux entiers."""
    assert type(a) == int , "a n'est pas un entier !"
    assert type(b) == int , "b n'est pas un entier !"
    res = a + b
    return res