# É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

<Mermaid
  chart={`flowchart TB
    a[Commentaire<br/>dans le code] --> la[Celui qui modifie cette ligne]
    b[Docstring<br/>en tête de fonction] --> lb[Celui qui appelle cette fonction]
    c[README<br/>à la racine] --> lc[Celui qui découvre le projet]
    d[Documentation<br/>un site comme celui-ci] --> ld[Celui qui veut comprendre l'ensemble]`}
/>

| 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
# 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 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
#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 :

```text
pip freeze > requirements.txt
pip install -f requirements.txt
```

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 :

````md
# 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 :

| Type | But | Exemple |
| --- | --- | --- |
| Tutoriel | Apprendre en faisant | [Les cours de ce site](/presentation) |
| Guide pratique | Réussir une tâche précise | [Ajouter un cours](/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.

<Mermaid
  chart={`flowchart LR
    a[Je modifie le code] --> b{Une page décrit ce code ?}
    b -- oui --> c[Je la corrige dans le même commit]
    b -- non --> d{Le changement surprendrait un lecteur ?}
    d -- oui --> e[J'ajoute une ligne à la bonne page]
    d -- non --> f[Rien à faire]`}
/>

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.
