À quoi sert la documentation d’un programme Python ?

Réponse courte

La documentation explique aux utilisateurs comment se servir du programme et aux développeurs comment le comprendre et le reprendre. Elle précise notamment les entrées admises, les résultats, les limites et les choix utiles à connaître.

Comprendre

Aider la personne qui utilise le programme

Une documentation utilisateur décrit comment démarrer le logiciel, quelles données fournir et comment interpréter la réponse. Pour un catalogue de livres, elle peut préciser que True signifie disponible et que le résultat affiché compte ces valeurs. Sans cette convention, une même donnée risque d’être comprise dans le sens opposé.

Faciliter la reprise du code

La documentation destinée aux développeurs présente les fonctions, leurs paramètres, leurs résultats et leurs conditions d’utilisation. Elle peut expliquer pourquoi une fonction renvoie None quand aucun titre n’est trouvé, ou signaler qu’une fonction modifie un tableau. Ces informations aident une autre personne à appeler la fonction correctement et à corriger le programme sans deviner son contrat.

Écrire ce qui est utile

Un commentaire pertinent éclaire une décision ou une contrainte qui ne se lit pas directement dans le code. Il n’est pas nécessaire de traduire chaque instruction en français : un texte qui dit seulement « ajouter 1 au compteur » au-dessus de compteur = compteur + 1 répète le code. La documentation doit rester cohérente avec la version réelle, sinon elle induit en erreur.

Deux oublis à éviter

Ne décris pas seulement les fonctions sans expliquer comment lancer le programme ou quel résultat attendre. Ne présente pas non plus un test réussi sur une donnée comme une garantie de réussite sur toutes les données. Si le projet réutilise du code externe, indique les ressources et leurs licences : trouver un programme en ligne n’autorise pas automatiquement toute réutilisation.

Exemples

  • Une notice peut préciser que la fonction compter_disponibles reçoit une liste de booléens, où True signifie livre disponible, et renvoie un entier.
  • La documentation d’une recherche peut annoncer qu’un titre trouvé produit son indice et qu’un titre absent donne None.
  • Une note de projet peut signaler qu’un programme a été vérifié sur [True, False, True] et qu’il renvoie 2, sans en déduire une preuve universelle.

Pièges fréquents

  • Des commentaires qui répètent chaque ligne alourdissent le programme sans expliquer ses choix ni ses contraintes.
  • Omettre les conditions d’appel ou les limites peut conduire une autre personne à utiliser la fonction avec des données qu’elle ne sait pas traiter.

Pourquoi ça marche

Des explications à jour transmettent les conventions et les limites qui ne sont pas toujours évidentes à partir du seul comportement observé.

Et maintenant ?

Questions proches

← Toutes les questions-réponses