Accueil / Docstring

Docstring

Documenter ses fonctions, classes et modules Python directement dans le code, avec une syntaxe normée. Le moyen le plus simple d'expliquer ce que fait un bout de code à ton futur toi (et à tes collègues).

À quoi ça sert

Une docstring est une chaîne de caractères placée juste après la déclaration d'une fonction, classe ou module Python. Elle explique le rôle, les paramètres, la valeur de retour et les éventuelles exceptions.

Trois bonnes raisons d'en écrire :

  • Pour toi — survoler une fonction trois mois plus tard et comprendre son rôle sans la relire ligne à ligne.
  • Pour ton IDE — VS Code, PyCharm et autres affichent la docstring au survol et dans l'autocomplétion.
  • Pour la documentation auto — outils comme Sphinx, MkDocs ou la page /docs de FastAPI les exploitent pour générer une vraie doc.
À retenir

Une docstring n'est pas un simple commentaire : elle est accessible au runtime via fonction.__doc__ et par help(fonction).

Un exemple d'usage

Prenons une fonction utilitaire. Sans docstring :

python (sans doc) 
def moyenne(valeurs):
    return sum(valeurs) / len(valeurs)

Avec une docstring (style Google) :

python (avec doc) 
def moyenne(valeurs: list[float]) -> float:
    """Calcule la moyenne arithmétique d'une liste de nombres.

    Args:
        valeurs: Liste de nombres dont on veut la moyenne.

    Returns:
        La moyenne arithmétique.

    Raises:
        ZeroDivisionError: Si la liste est vide.

    Example:
        >>> moyenne([1, 2, 3])
        2.0
    """
    return sum(valeurs) / len(valeurs)

Maintenant, dans VS Code, quand tu survoleras moyenne(...), tu verras directement cette description, et help(moyenne) te l'affichera dans la console.

Les 3 styles principaux

Il n'y a pas de « bonne » réponse — c'est une convention d'équipe. Choisis-en un et tiens-toi à lui dans tout le projet.

Style Google (très lisible, recommandé pour débuter)

python 
def diviser(a: float, b: float) -> float:
    """Divise a par b.

    Args:
        a: Le numérateur.
        b: Le dénominateur (non nul).

    Returns:
        Le résultat de a / b.

    Raises:
        ValueError: Si b vaut 0.
    """

Style NumPy (très utilisé en data science)

python 
def diviser(a: float, b: float) -> float:
    """Divise a par b.

    Parameters
    ----------
    a : float
        Le numérateur.
    b : float
        Le dénominateur (non nul).

    Returns
    -------
    float
        Le résultat de a / b.

    Raises
    ------
    ValueError
        Si b vaut 0.
    """

Style reStructuredText / Sphinx (par défaut de Sphinx)

python 
def diviser(a: float, b: float) -> float:
    """Divise a par b.

    :param a: Le numérateur.
    :param b: Le dénominateur (non nul).
    :return: Le résultat de a / b.
    :raises ValueError: Si b vaut 0.
    """
Conseil perso

Le style Google est le plus lisible et celui qui rend le mieux dans l'auto-completion VS Code. C'est mon défaut.

How-to : bien documenter avec VS Code

  1. Installer l'extension autoDocstring

    autoDocstring (id : njpwerner.autodocstring) génère le squelette d'une docstring à partir de la signature de ta fonction. Énorme gain de temps.

    1. Ouvre VS Code → onglet Extensions (Ctrl+Shift+X).
    2. Cherche autoDocstring et installe.
    3. Choisis le format dans les paramètres : Auto Docstring: Docstring Format → google (ou numpy, sphinx).

  2. Générer une docstring en 1 raccourci

    1. Place le curseur sur la ligne juste sous la signature de la fonction.
    2. Tape """ puis appuie sur Entrée.
    3. L'extension génère le squelette avec Args, Returns, Raises en fonction de la signature.
    4. Il ne reste qu'à remplir les descriptions.
    Astuce

    Plus tu mets de type hints dans ta signature, plus le squelette généré est précis (types pré-remplis).

  3. Configurer le style par défaut dans le projet

    Crée .vscode/settings.json :

    json 
    {
    "autoDocstring.docstringFormat": "google",
    "autoDocstring.startOnNewLine": true,
    "autoDocstring.guessTypes": true
}

  4. Vérifier la qualité avec un linter

    pydocstyle (ou son successeur ruff) vérifie que tes docstrings respectent une convention.

    bash 
    uv add --dev ruff
uv run ruff check .

    Pour activer les règles docstring, ajoute dans pyproject.toml :

    toml 
    [tool.ruff.lint]
select = ["D"]   # règles pydocstyle

[tool.ruff.lint.pydocstyle]
convention = "google"

  5. Tester ses exemples avec doctest

    Si tu mets des >>> dans tes docstrings, Python peut tester que les exemples renvoient bien ce que tu prétends :

    bash 
    uv run python -m doctest mon_module.py -v

    Si la doc dit moyenne([1, 2, 3]) == 2.0 mais que la fonction renvoie autre chose, doctest te le signale.

  6. Générer un site de doc avec Sphinx ou MkDocs

    Quand tes docstrings sont en place, tu peux les transformer en site web navigable avec deux outils principaux :

    bash 
    # Option 1 : Sphinx (le classique)
uv add --dev sphinx sphinx-rtd-theme

# Option 2 : MkDocs + mkdocstrings (plus moderne)
uv add --dev mkdocs mkdocs-material mkdocstrings[python]

Bonnes pratiques

  • Première ligne courte et au présent — résume en une phrase ce que fait la fonction (pas « cette fonction calcule… », mais « calcule… »).
  • Documente le pourquoi, pas le comment — le code dit déjà comment, la docstring dit à quoi ça sert et quand l'utiliser.
  • Reste cohérent dans tout le projet : un seul style, partout.
  • Type hints + docstring = combo gagnant. Les types vivent dans la signature, la prose dans la docstring.
  • Mets à jour la docstring quand tu changes la fonction. Une doc fausse est pire qu'une doc absente.

Pour aller plus loin