docstrings et aide intégrée

dans cette leçon, vous allez apprendre à écrire des docstrings pour documenter votre code directement dans les fonctions, classes et modules, et à utiliser l’aide intégrée de python.

objectifs

comprendre ce qu’est une docstring et à quoi elle sert
documenter une fonction, une classe ou un module
consulter la documentation avec help() et .__doc__
appliquer un format clair et cohérent

qu’est-ce qu’une docstring ?

une docstring est une chaîne de caractères placée en première ligne d’un module, d’une fonction, d’une classe ou d’une méthode. elle décrit brièvement ce que fait l’élément.

def aire_cercle(r):
    """calcule l'aire d'un cercle de rayon r."""
    import math
    return math.pi * r ** 2

afficher l’aide

help() lit la docstring :

help(aire_cercle)

accéder directement à la docstring :

print(aire_cercle.__doc__)

docstring de module

en haut du fichier python :

"""outils de calculs géométriques simples."""

docstring de classe

class Rectangle:
    """représente un rectangle avec largeur et hauteur."""
    def __init__(self, l, h):
        self.l = l
        self.h = h

formats courants

style simple (pour fonctions courtes)

def add(a, b):
    """retourne la somme de a et b."""
    return a + b

style multi-lignes

def distance(x1, y1, x2, y2):
    """
    calcule la distance euclidienne entre deux points.

    paramètres:
        x1, y1 -- coordonnées du premier point
        x2, y2 -- coordonnées du second point

    retourne:
        float -- distance entre les deux points
    """
    import math
    return math.hypot(x2 - x1, y2 - y1)

style type hints + docstring

def greet(name: str) -> str:
    """retourne un message de salutation pour name."""
    return f"bonjour {name}"

bonnes pratiques

phrase courte et claire sur la première ligne
si besoin, une ligne vide puis des détails
décrire paramètres et valeurs de retour
garder la docstring synchronisée avec le code
pas de détails inutiles dans les petites fonctions triviales

mini exemples exécutables

def moyenne(*nombres):
    """
    retourne la moyenne des nombres donnés.

    si aucun nombre n'est fourni, retourne None.
    """
    if not nombres:
        return None
    return sum(nombres) / len(nombres)

help(moyenne)

"""outils simples pour le module principal."""

def info():
    """affiche un message d'info."""
    print("module d'exemple prêt")

class Compteur:
    """compteur simple qui peut être incrémenté."""
    def __init__(self, start=0):
        """initialise le compteur avec une valeur de départ."""
        self.value = start

    def inc(self):
        """incrémente le compteur de 1."""
        self.value += 1

pièges courants

oublier de mettre la docstring en première ligne → elle ne sera pas détectée
écrire une docstring trompeuse qui ne correspond pas au code
mettre trop de détails dans une fonction triviale → alourdit la lecture
négliger la mise à jour après une modification du code

exercices

écrire une fonction perimetre_cercle(r) avec une docstring claire et tester avec help().
ajouter une docstring multi-lignes à une fonction qui calcule la moyenne de 3 nombres.
créer une classe Personne avec docstring et méthodes documentées (parler, se_presenter).
écrire un module utils.py avec docstring de module + une fonction documentée.
afficher .__doc__ pour une fonction standard (len, print).

Menu