Aller au contenu

Écrire une documentation

Le carnet de bord du projet le dit sans détour : « oublier comment fonctionne son propre code après une interruption est le problème n°1 ». La documentation est la réponse. Ce cours explique quoi écrire, où, et pour qui.

Le problème

Le projet contient beaucoup d'écrits : des commentaires dans le code, une liste de 70 idées en bas de game.py, neuf fichiers dans documentation/. Et pourtant son auteur ne s'y retrouve plus.

Ce n'est pas un manque de quantité. C'est que chaque information n'est pas au bon endroit.

Quatre niveaux, quatre lecteurs

NiveauRépond àDurée de vie
CommentairePourquoi cette ligne est écrite ainsi ?Tant que la ligne existe
DocstringQue fait cette fonction, que lui donner, que rend-elle ?Tant que la fonction existe
READMEQu'est-ce que c'est, comment je le lance ?Tout le projet
DocumentationComment est-ce organisé, pourquoi ces choix ?Tout le projet

Les commentaires

Un commentaire explique pourquoi, jamais quoi. Le code dit déjà ce qu'il fait.

Python
# inutile : répète le code self.turn += 1 # on ajoute 1 au tour # utile : explique une décision self.food_expansion = [0, BASE_EXPANSION_FOOD_NEEDED] # list car bugs quand tuple

Le projet contient de très bons commentaires de ce type. Par exemple dans find_neighbors, celui qui explique que les voisins diffèrent selon la parité de la ligne, avec le lien vers la référence utilisée.

Les notes « à faire »

Les 70 lignes en bas de game.py sont précieuses, mais mal placées : elles sont loin du code qu'elles concernent, et rien n'indique lesquelles sont encore vraies.

Type de noteMeilleure place
Défaut d'une fonction préciseUn commentaire # TODO: juste au-dessus
Idée de fonctionnalitéUn fichier de suivi, ou les tickets du dépôt
Question de conceptionLa documentation, section des questions ouvertes

La convention # TODO: est reconnue par les éditeurs, qui savent en faire la liste.

Le code commenté

Le projet garde beaucoup de lignes désactivées :

Python
#self.max_movement = movement self.max_movement = self.stats["movement"]

On le fait par prudence. Mais Git garde déjà toutes les anciennes versions. Le code commenté encombre la lecture et finit par ne plus correspondre à rien. On supprime, on fait un commit.

Les docstrings

Une docstring est une chaîne placée juste sous la ligne def ou class. Python la reconnaît : l'éditeur l'affiche au survol, et help(fonction) la montre.

Python
def find_neighbors(coo): """Renvoie les coordonnées des six voisins d'une case. La grille est en odd-r : les lignes impaires sont décalées d'une demi-case vers la droite, donc les voisins dépendent de la parité de la ligne. Args: coo: tuple (colonne, ligne). Returns: Liste de six tuples, dans le sens horaire en partant de la droite. Les coordonnées peuvent être hors de la carte. """

Trois parties : une phrase de résumé, les explications utiles, puis les paramètres et le résultat.

Tout n'en a pas besoin. On documente en priorité :

  • les fonctions appelées depuis d'autres fichiers ;
  • celles dont le comportement n'est pas évident ;
  • celles qui ont un piège, comme ici « peuvent être hors de la carte ».

Les annotations de type

Elles complètent la docstring en disant ce que la fonction attend et rend.

Python
def find_neighbors(coo: tuple[int, int]) -> list[tuple[int, int]]:

Python ne les vérifie pas à l'exécution, mais l'éditeur s'en sert pour signaler les erreurs. Le bug des coordonnées en liste ou en tuple aurait été signalé avant même de lancer le jeu.

Le README

C'est la première page que voit quelqu'un qui arrive. Celui du projet contient aujourd'hui deux lignes :

Code
pip freeze > requirements.txt pip install -f requirements.txt

Un README utile répond à cinq questions :

QuestionContenu
Qu'est-ce que c'est ?Une phrase, une capture d'écran
Comment l'installer ?Les commandes, dans l'ordre
Comment le lancer ?La commande exacte, depuis quel dossier
Comment y jouer ?Les touches principales
Où en savoir plus ?Un lien vers la documentation

Exemple pour ce projet :

MarkdownMarkdown
# BestGameOfTheYear Jeu de stratégie 4X au tour par tour sur grille hexagonale, en Python avec Pygame. ## Installation ```bash python -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ## Lancer le jeu Depuis la racine du projet : ```bash python src/main.py ``` ## Documentation ```bash cd docs && npm install && npm run dev ```

Au passage : la commande d'installation est pip install -r, avec un r. L'option -f du README actuel fait autre chose.

La documentation

Un site comme celui-ci, ou comme celui du jeu dans son dossier docs/. Elle contient ce qui ne tient ni dans un commentaire ni dans un README : la vue d'ensemble, les schémas, les décisions.

Une bonne documentation sépare quatre types de pages, parce qu'on ne les lit pas dans le même état d'esprit :

TypeButExemple
TutorielApprendre en faisantLes cours de ce site
Guide pratiqueRéussir une tâche préciseAjouter un cours, et Migration dans la documentation du jeu
RéférenceRetrouver une information exacteLes règles et Les commandes, dans la documentation du jeu
ExplicationComprendre pourquoiQualité du code et Principes, dans la documentation du jeu

Mélanger les quatre dans une même page donne un texte où l'on ne trouve rien.

Écrire pour être lu

Quelques règles qui valent pour tous les niveaux.

  • Commencer par l'essentiel. La première phrase dit de quoi il s'agit.
  • Écrire pour quelqu'un qui n'était pas là. Dans six mois, ce quelqu'un sera vous.
  • Un exemple vaut mieux qu'une définition. Montrer le code, la commande, le résultat.
  • Dire ce qui n'est pas fait. Une page qui présente comme existant ce qui est prévu fait perdre du temps.
  • Dater ce qui vieillit. Un état des lieux sans date ne vaut plus rien au bout de quelques semaines.

Garder la documentation vivante

Une documentation fausse est pire qu'une documentation absente : on lui fait confiance.

Trois habitudes qui suffisent :

  1. Même commit. Le code et sa documentation changent ensemble.
  2. Peu, mais juste. Mieux vaut dix pages à jour que cinquante douteuses.
  3. Relire avant une pause. Avant d'arrêter un projet quelques semaines, noter où l'on en est. C'est le moment où l'on en sait le plus.

À retenir

  • Commentaire : pourquoi. Docstring : comment s'en servir. README : comment démarrer. Documentation : comment c'est organisé.
  • Supprimer le code commenté, Git s'en souvient.
  • Une information par endroit, au plus près de ce qu'elle décrit.
  • La documentation se modifie dans le même commit que le code.

Exercices

  1. Réécrire le README.md du projet avec les cinq rubriques.
  2. Ajouter une docstring à Map.find_neighbors, Player.finish_turn et City.expand.
  3. Parcourir les notes en bas de game.py. Les classer : déjà fait, encore vrai, plus d'actualité. Déplacer celles qui restent au bon endroit.
  4. Supprimer le code commenté de units.py. Lancer le jeu, faire un commit.