Les schémas Mermaid
Mermaid transforme du texte en schéma. On écrit quelques lignes, l'outil dessine. Le schéma vit dans le même dépôt que le code, se modifie comme du code, et se relit dans un commit.
Le problème
Quand un projet dépasse quelques fichiers, on ne peut plus le garder en tête. On perd la vue d'ensemble : qui appelle qui, dans quel ordre, quelles sont les étapes.
Un schéma remet cette vue sous les yeux. Mais un schéma dessiné à la souris est long à faire, et personne ne le met à jour. Un schéma en texte se corrige en dix secondes.
Un schéma répond à une question
L'erreur classique est de vouloir tout montrer. Un bon schéma répond à une seule question. On choisit le type d'après la question.
| Question | Type Mermaid | Exemple dans la documentation du jeu |
|---|---|---|
| Dans quel ordre ça se passe ? Quels sont les choix ? | flowchart | A* |
| Qui appelle qui, et dans quel ordre ? | sequenceDiagram | Tour par tour |
| Quelles classes existent, que contiennent-elles ? | classDiagram | Les classes |
| Dans quels états peut-on être ? | stateDiagram- | Modes en partie |
| À quoi ressemblent les données ? | erDiagram | Plus bas sur cette page |
| Comment c'est rangé ? | flowchart avec subgraph | Les dossiers |
Écrire un schéma dans ce site
Dans un fichier .mdx, on utilise le composant Mermaid :
TSX
Pour mettre au point un schéma avant de le coller : mermaid.live affiche le résultat pendant qu'on tape.
flowchart : un déroulé avec des choix
Le plus utilisé. La première ligne donne le sens : LR de gauche à droite, TB de haut en bas.
Code
Les formes ont un sens, et le respecter aide à la lecture :
| Écriture | Forme | Usage |
|---|---|---|
a[texte] | Rectangle | Une action |
a{texte} | Losange | Une question |
a([texte]) | Arrondi | Un début ou une fin |
a((texte)) | Cercle | Un point, un nœud de graphe |
a[(texte)] | Cylindre | Des données stockées |
Et les flèches :
| Écriture | Rendu | Usage |
|---|---|---|
a --> b | Flèche pleine | Enchaînement |
a -- | Flèche avec étiquette | Réponse à une question |
a -.-> b | Pointillés | Lien indirect, optionnel |
a ==> b | Trait épais | Lien important |
Pour regrouper des boîtes, subgraph nom [Titre] puis end.
sequenceDiagram : qui appelle qui
Chaque colonne est un objet, le temps descend. C'est le meilleur schéma pour repérer une fonction qui touche à trop de choses : plus il y a de colonnes traversées, plus le code est couplé.
Code
| Écriture | Sens |
|---|---|
A- | A appelle B |
B-- | B répond à A |
Note over A: | Une remarque |
loop texte puis end | Une répétition |
opt texte puis end | Un passage facultatif |
classDiagram : les classes et leurs liens
Code
| Écriture | Sens |
|---|---|
A <|-- B | B hérite de A |
A *-- B | A possède B et le crée |
A o-- B | A garde une référence vers B |
A --> B | A utilise B |
A ..> B | A dépend de B, sans le garder |
Conseil : ne pas tout mettre. Un schéma avec les seuls liens, puis un schéma détaillé par groupe de classes, se lit mieux qu'un grand schéma complet.
stateDiagram-v2 : des états et des transitions
Idéal pour les menus, et pour tout ce qui est « un mode à la fois ».
Code
[*] marque le début et la fin. Le texte après les deux-points est l'événement qui déclenche le changement.
Ce schéma révèle souvent des oublis : un état dont on ne peut pas sortir, ou une transition qu'on n'avait pas prévue.
erDiagram : la forme des données
Utile pour un fichier de sauvegarde ou une base de données. Voici le fichier save_N.json écrit par Saves_ :
Les symboles entre deux entités indiquent combien : une barre pour « un », une patte d'oie pour « plusieurs », un rond pour « zéro possible ».
La méthode
-
Écrire la question en une phrase. « Que se passe-t-il quand le joueur finit son tour ? »
-
Choisir le type dans le tableau du haut.
-
Dessiner ce qui existe, en lisant le code, sans rien corriger.
-
Repérer ce qui gêne : flèches qui se croisent, boîte reliée à tout le monde, colonne traversée dix fois.
-
Dessiner la version souhaitée. L'écart entre les deux schémas est le plan de travail.
L'étape 3 est la plus utile et la plus négligée. Dessiner ce qu'on croit avoir écrit ne sert à rien. Dessiner ce qui est réellement écrit fait apparaître les problèmes.
Les erreurs fréquentes
| Erreur | Effet | Correction |
|---|---|---|
| Trop de boîtes | Illisible | Un schéma par question, une quinzaine de boîtes au plus |
| Texte long dans une boîte | Boîtes énormes | Quelques mots. Le détail va dans le texte autour |
| Mélanger les niveaux | Confusion | Ne pas mettre des dossiers et des fonctions dans le même schéma |
| Aucune légende | Le lecteur devine | Une phrase avant le schéma : ce qu'il montre, comment le lire |
| Schéma jamais mis à jour | Il ment | Le modifier dans le même commit que le code |
Les pièges d'écriture
| Problème | Cause | Solution |
|---|---|---|
| Le schéma ne s'affiche pas | Parenthèses ou deux-points dans une étiquette | Mettre l'étiquette entre guillemets doubles |
| Retour à la ligne dans une boîte | Écrire <br/> | |
| Identifiant refusé | Mot réservé comme end | Choisir un autre identifiant |
| Accent grave dans le schéma | Il ferme le texte du composant | Ne pas en mettre |
À retenir
- Un schéma, une question.
- Le type se choisit d'après la question.
- Dessiner d'abord ce qui existe.
- Un schéma se met à jour avec le code.
Exercices
- Dessiner en
flowchartce que fait la touche B dans le jeu. - Dessiner en
sequenceDiagramce qui se passe quand le joueur fonde une ville avec la touche A. Combien d'objets sont traversés ? - Dessiner en
stateDiagram-les états d'une unité : en attente, sélectionnée, en déplacement, morte.v2 - Reprendre un schéma de la documentation du jeu, trouver ce qui a changé dans le code depuis, et le corriger.