Les bonnes pratiques

Des noms parlants pour les variables et les fonctions

Il est souhaitable de prendre l'habitude de donner des noms parlants aux variables et aux fonctions utilisées.

Des commentaires dans le code

Il est souhaitable de prendre l'habitude de mettre des commentaires de son code.

En Python, les lignes de commentaires commence par un # .

# Ceci est un commentaire...

Des docstrings pour les fonctions

Lors de la définition d'une fonction, il est nécessaire de renseigner cette fonction.

def nom_fct(a, b):
    '''
    Phrase expliquant le rôle de la fonction

    :param a: (type) explication
    :param b: (type) explication
    :return: (type) explication
    :CU: explications (CU = condition d'utilisation)
    :effet de bord: explication
    '''

    instructions
    ...
    instructions
    return valeur

Remarque : le texte écrit entre les triples apostrophes est celui qui s'affiche lorsqu'on utilise la fonction help avec une fonction comme paramètre.

Le module doctest

Principe général

Il est possible, pour les fonction simples, de rédiger des tests unitaires dans le docstring d'une fonction

Le module doctest permet alors de tester cela.

Exemple complet

def add(a, b):
    """
    Addition de deux nombres.
    
    :param a: (int ou float) premier nombre à additionner.
    :param b: (int ou float) deuxième nombre à additionner.
    :CU: a et b doivent être des entier ou des nombres à virgule.
    :return: (int ou float) retourne la somme des deux nombres 
        passés en paramètre.

    :Exemple:
    >>> add(1, 1)
    2
    >>> add(2.1, 3.4)
    5.5
    """
    return a + b
 
# Lignes de code à mettre en fin de script afin de lancer les doctest
if __name__ == "__main__":
    import doctest
    doctest.testmod()

L'execussion de ce script ne va rien renvoyer car les deux tests donnent les bons résultats.

Si l'on complète la fonction testmod de la dernière ligne avec le paramètre verbose=True, l'exécussion du script va détailler les tests.

if __name__ == "__main__":
    import doctest
    doctest.testmod(verbose=True)