Les docstrings

Un code qui fonctionne est un bon début ; un code compréhensible par un collègue (ou par vous-même dans 6 mois) est bien mieux. Les docstrings sont l'outil Python standard pour documenter vos fonctions, modules et classes. Ce chapitre est court mais essentiel : le TOSA teste les docstrings au niveau Opérationnel et Avancé.

Les commentaires (#) — rappel

Les commentaires (#) sont ignorés par l'interpréteur. Ils expliquent un choix dans le code.

# Ceci est un commentaire, Python l'ignore
x = 10          # commentaire en fin de ligne

Règle : un bon commentaire explique le POURQUOI, pas le QUOI. Le code dit déjà ce qu'il fait ; le commentaire doit apporter un contexte non évident.

# ❌ Inutile : redit ce que fait le code
x = x + 1    # ajoute 1 à x

# ✅ Utile : explique une décision non évidente
x = x + 1    # on compense l'indice qui commence à 0 côté base de données

Les docstrings

Une docstring (documentation string) est une chaîne de documentation placée :

• Juste après la signature d'une fonction, d'une classe ou d'un module.
• Entre triples guillemets """...""".

def moyenne(notes):
    """Calcule la moyenne d'une liste de notes."""
    return sum(notes) / len(notes)

print(moyenne([12, 15, 14]))

Contrairement à un commentaire #, la docstring :

1. Est associée à l'objet (fonction, classe…).
2. Est accessible à l'exécution via __doc__ ou help().
3. Est affichée par les outils de documentation (Sphinx, IDE, etc.).

Accéder à une docstring

Deux façons :

def moyenne(notes):
    """Calcule la moyenne d'une liste de notes."""
    return sum(notes) / len(notes)

# Méthode 1 : attribut __doc__
print(moyenne.__doc__)

La seconde méthode est help() (à utiliser dans l'interpréteur interactif) :

help(moyenne)
# Help on function moyenne in module __main__:
#
# moyenne(notes)
#     Calcule la moyenne d'une liste de notes.

help() est particulièrement pratique dans l'interpréteur interactif : tapez help(print) pour voir l'aide d'une fonction native.

Docstring courte (une ligne)

Pour des fonctions simples :

def carre(x):
    """Renvoie le carré de x."""
    return x * x

print(carre.__doc__)

Convention : commencer par un verbe d'action (Renvoie, Calcule, Affiche…) et terminer par un point.

Docstring longue (multi-lignes)

Pour des fonctions plus complexes, on structure la docstring :

def statistiques(notes):
    """Calcule min, max et moyenne d'une liste de notes.

    Arguments:
        notes: liste de nombres (entiers ou flottants).

    Renvoie:
        Un tuple (minimum, maximum, moyenne).

    Exemple:
        >>> statistiques([12, 15, 9])
        (9, 15, 12.0)
    """
    return min(notes), max(notes), sum(notes) / len(notes)

print(statistiques.__doc__)

La structure :

1. Première ligne : résumé en une phrase.
2. Ligne vide.
3. Paragraphe(s) détaillés : arguments, retour, exemples, exceptions.