Documenter son code Python avec une docstring
La documentation est souvent ce qui différencie un bon code d’un excellent code.
En Python, les docstrings permettent de documenter efficacement nos fonctions, classes, modules et scripts.
Un code bien documenté est plus lisible, plus facile à maintenir et plus simple à tester – surtout en équipe ou pour vous-même quelques mois plus tard ! 😋
Une docstring (qui est la contraction de DOCumentation STRING) est donc une chaîne de caractères placée juste après la déclaration d’une fonction, d’une classe ou d’un module. Elle sert à expliquer ce que fait ce bloc de code, quels arguments il attend, et ce qu’il retourne.
Syntaxe d'une docstring
La syntaxe des docstrings est simple, mais obéit à des règles précises pour être utile et cohérente.
Syntaxe de base
def saluer(nom):
"""Retourne une salutation avec le nom fourni."""
return f"Bonjour {nom} !"La docstring est toujours :
- Placée immédiatement après la déclaration de la fonction (ou de la classe/module) ;
- Entourée de triple guillemets (
"""...""") ou de triples guillemets simples ('''...''') ; - Composée d’une phrase courte en style impératif (sans "Cette fonction permet de...").
Exemple incorrect
Trop souvent, les développeurs Python confondent les docstrings avec les commentaires.
def saluer(nom):
# Ceci est un commentaire, pas une docstring
return f"Bonjour {nom}"Ce commentaire ne sera pas reconnu comme une docstring par help() ou les outils de documentation (qu'on verra juste après).
Même pour les fonctions très simples, une docstring bien écrite clarifie l’intention du développeur, même si l’implémentation est évidente.
PEP 257 : la convention officielle des docstrings
Python repose sur des conventions pour écrire un code lisible. Pour les docstrings, la référence est la PEP 257 (Python Enhancement Proposal 257 🇺🇸).
C'est une convention qui dicte les règles formelles pour rédiger des docstrings claires et cohérentes dans les fonctions, classes, modules et packages Python.
Voici donc les principes clés à respecter :
- Une docstring commence toujours par une phrase en style impératif décrivant brièvement le comportement ;
- Si nécessaire, une ligne vide sépare cette phrase d’une description plus détaillée ;
- Pour les fonctions, on décrit les paramètres et le résultat retourné ;
- La docstring est placée juste après la déclaration, avant tout code exécutable.
Cet exemple est conforme :
def addition(a, b):
"""Additionne deux nombres.
Args:
a (int): premier nombre
b (int): second nombre
Returns:
int: la somme de a et b
"""
return a + b
Docstring dans les fonctions
La forme la plus courante de docstring est celle qu’on associe aux fonctions. Bien rédigée, elle sert autant aux utilisateurs de la fonction qu’à ceux qui maintiendront le code.
Exemple dans une fonction
def moyenne(notes):
"""Calcule la moyenne d'une liste de notes.
Args:
notes (list of float): liste des notes
Returns:
float: moyenne calculée
"""
return sum(notes) / len(notes)
Les modèles de docstring
Quand nous écrivons une docstring, il convient de rester sur la même structure.
Autrement dit, il ne faut pas changer notre manière de documenter notre code d'une fonction à une autre.
Par exemple, voici deux styles très connus : Google Style et NumPy Style.
Google Style
def nom(param1, param2):
"""Brève description.
Args:
param1 (type): description
param2 (type): description
Returns:
type: description du retour
"""
NumPy Style
def nom(param1, param2):
"""
Brève description
Parameters
----------
param1 : type
Description
param2 : type
Description
Returns
-------
type
Description
"""C'est important de choisir un style unique (Google, NumPy, etc) pour tout son projet, pour garantir la cohérence de la documentation.
Docstring dans les classes et les méthodes
Les classes et leurs méthodes peuvent également être documentées avec des docstrings.
class Chien:
"""Représente un chien domestique."""
def __init__(self, nom):
"""Initialise le nom du chien.
Args:
nom (str): le nom du chien
"""
self.nom = nom
def aboyer(self):
"""Affiche un aboiement."""
print(f"{self.nom} aboie !")Ici, on documente notre classe (Chien), ainsi que son constructeur (__init__) et sa méthode (aboyer).
On crée donc trois docstrings.
Une méthode héritée d'une classe parente conserve la docstring d'origine, sauf si on la redéfinit. Il est donc recommandé de documenter les méthodes même dans les sous-classes si leur comportement diffère. 😊
Docstring dans les modules et les scripts
Une docstring peut aussi être placée en tête d’un fichier Python (script ou module). Elle décrit le rôle général du fichier, les dépendances, ou les points d’entrée.
Exemple de docstring de module
"""
Ce module gère les opérations mathématiques élémentaires.
Fonctions :
- addition(a, b)
- soustraction(a, b)
"""
def addition(a, b):
return a + b
Recommandations
Pour faire une docstring dans un module, c'est important de toujours la placer tout en haut du fichier, juste après les éventuelles déclarations.
Elle est très utile pour les packages, car elle sera affichée dans
help(mon_module).
Accéder aux docstrings
Les docstrings ne sont pas seulement destinées aux lecteurs humains : elles sont accessibles dynamiquement, ce qui les rend utiles dans les IDE, terminaux ou outils de documentation.
Par help()
help(print)
help(ma_fonction)Affiche la docstring directement dans le terminal ou le notebook.
Par .__doc__
print(print.__doc__)Retourne la docstring en tant que chaîne de caractères.
Dans un IDE
Dans PyCharm, VS Code ou JupyterLab :
- survol de fonction -> affichage automatique ;
- suggestions contextuelles -> docstring visible en info-bulle.
Ajouter une docstring permet à l’éditeur de proposer de l’autocomplétion enrichie, ce qui améliore considérablement l’expérience de développement.
Générer de la documentation automatiquement
Une docstring bien structurée ouvre la porte à la génération automatique de documentation HTML, PDF ou Markdown, à partir du code lui-même. 👀
Voici certains des outils les plus populaires pour générer vos documentations automatiquement.
| Outil | Format d'entrée | Format de sortie | Projet typique |
| Sphinx | reStructuredText | HTML, PDF, EPUB | Documentation python officielle |
| pdoc | docstrings | HTML, Markdown | Petits projets Python |
| mkdocstrings | Markdown | HTML (site statique) | Intégration MkDocs |
Docstring vs commentaires : quelles différences ?
Les commentaires (#) et les docstrings (""") ont des fonctions bien distinctes, même s’ils documentent tous deux le code.
| Aspect | Commentaire (#) | Docstring (""") |
| Portée | Ligne ou bloc | Fonction, classe, module, script |
| Accessibilité | Invisible à l'exécution | Accessible via help() ou .__doc__ |
| Usage principal | Explication de logique rapide | Description officielle d'une fonction, etc |
| Standardisation | Libre | Doit respecter les conventions PEP-257 |
Finalement, les docstrings ne remplacent pas les commentaires. En fait ils sont complémentaires :
- On utilise les docstrings pour la documentation externe ;
- Puis les commentaires pour expliquer des choix de code complexes.
Erreurs fréquentes sur les docstrings
Mal rédiger ou oublier une docstring peut nuire à la qualité globale du code.
Voici les pièges courants à éviter.
Ne pas écrire de docstring
Même pour des fonctions simples, il est recommandé d’ajouter au moins une ligne expliquant ce que fait la fonction rapidement.
Écrire une docstring trop vague
def process(data):
"""Fait quelque chose."""Ce type de docstring est inutile. Il vaut mieux ne rien écrire que d’induire en erreur.
Répéter bêtement le nom de la fonction
def addition(a, b):
"""Additionne a et b.""" # 🚫 Trop redondantC'est mieux d'expliquer vraiment l'intérêt d'une fonction.
"""Retourne la somme de deux entiers."""
Les docstrings et les tests
Une docstring peut aussi être utilisée pour intégrer des tests automatisés directement dans le code via les doctests.
def carre(x):
"""Calcule le carré d’un nombre.
>>> carre(3)
9
>>> carre(-4)
16
"""
return x * xPour les exécuter :
python -m doctest mon_script.pyCela permet d’illustrer les cas d’usage et de vérifier automatiquement leur validité. Parfait pour la pédagogie ou les bibliothèques open-source.
Questions fréquentes sur les docstrings
Que se passe-t-il si je n’écris pas de docstring ?
Rien. Votre code fonctionnera, mais il sera plus difficile à maintenir à la fois pour vous et pour l'équipe qui peut travailler avec vous sur vos projets.
Comment puis-je apprendre Python ?