É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
| Niveau | Répond à | Durée de vie |
|---|---|---|
| Commentaire | Pourquoi cette ligne est écrite ainsi ? | Tant que la ligne existe |
| Docstring | Que fait cette fonction, que lui donner, que rend-elle ? | Tant que la fonction existe |
| README | Qu'est-ce que c'est, comment je le lance ? | Tout le projet |
| Documentation | Comment 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
Le projet contient de très bons commentaires de ce type. Par exemple dans find_, 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 note | Meilleure place |
|---|---|
| Défaut d'une fonction précise | Un commentaire # TODO: juste au-dessus |
| Idée de fonctionnalité | Un fichier de suivi, ou les tickets du dépôt |
| Question de conception | La 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
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
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
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
Un README utile répond à cinq questions :
| Question | Contenu |
|---|---|
| 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 :
Markdown
Au passage : la commande d'installation est pip install -, 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 :
| Type | But | Exemple |
|---|---|---|
| Tutoriel | Apprendre en faisant | Les cours de ce site |
| Guide pratique | Réussir une tâche précise | Ajouter un cours, et Migration dans la documentation du jeu |
| Référence | Retrouver une information exacte | Les règles et Les commandes, dans la documentation du jeu |
| Explication | Comprendre pourquoi | Qualité 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 :
- Même commit. Le code et sa documentation changent ensemble.
- Peu, mais juste. Mieux vaut dix pages à jour que cinquante douteuses.
- 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
- Réécrire le
README.mddu projet avec les cinq rubriques. - Ajouter une docstring à
Map.,find_ neighbors Player.etfinish_ turn City.expand. - 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. - Supprimer le code commenté de
units.py. Lancer le jeu, faire un commit.