Lab 1.6 : Le Scribe

Module : 1.6 - Génération de Documentation | ← SlidesDurée : 40 minutes Projet Exemple : node-express-mongoose-demo

Objectifs d'Apprentissage

À la fin de ce lab, vous serez capable de :

• Générer de la documentation inline (JSDoc/docstrings) avec Claude
• Créer des fichiers README au niveau des modules
• Valider la documentation générée par rapport au comportement réel
• Identifier où la documentation générée par l'IA pourrait être inexacte

Prérequis

• Labs 1.2, 1.3 et 1.5 complétés
• Compréhension de la structure du projet et des dépendances

Avertissement Important

La Documentation est une Hypothèse

Claude génère la documentation par inférence, pas en exécutant le code. Les docs générées sont des hypothèses sur ce que fait le code. Validez toujours par rapport aux tests et au comportement à l'exécution.

Configuration

# Naviguer vers le projet exemple
cd sample-projects/node-express-mongoose-demo

# Démarrer Claude Code
claude

---

Tâche 1 : Trouver le Code Non Documenté

Durée : 5 minutes

Identifiez les fonctions ou fichiers qui ont besoin de documentation.

Prompts à essayer :

Montre-moi les fonctions dans ce codebase qui n'ont pas de commentaires.

Quels fichiers dans le répertoire app/ ont le moins de documentation ?

Choisissez une cible : Sélectionnez une fonction ou un fichier qui :

• Semble important (utilisé à plusieurs endroits)
• N'a pas ou peu de commentaires
• Que vous ne comprenez pas entièrement

Critères de réussite :

• [ ] Identifié au moins 2-3 fonctions non documentées
• [ ] Sélectionné une fonction à documenter

---

Tâche 2 : Générer la Documentation Inline

Durée : 15 minutes

Ajoutez des commentaires JSDoc aux fonctions non documentées.

Prompts à essayer :

Ajoute des commentaires JSDoc à la fonction create dans app/controllers/articles.js

Ajoute de la documentation à toutes les méthodes publiques dans app/models/article.js

Examinez le résultat : Est-ce qu'il explique :

• Ce que fait la fonction ?
• Quels paramètres elle accepte ?
• Ce qu'elle retourne ?
• Les cas limites ou les erreurs ?

Étape de validation :

Montre-moi les tests pour cette fonction.

Comparez la documentation de Claude avec ce que les tests vérifient réellement.

Critères de réussite :

• [ ] Généré du JSDoc pour au moins 2 fonctions
• [ ] Validé la documentation par rapport aux tests (si disponibles)
• [ ] Identifié toute divergence

---

Tâche 3 : Générer la Documentation de Module

Durée : 20 minutes

Créez un README pour un module ou un répertoire.

Prompts à essayer :

Génère un fichier README.md pour le répertoire app/models. Inclure :
- L'objectif du module
- Les composants principaux et leurs responsabilités
- Des exemples d'utilisation

Crée de la documentation pour le module app/controllers expliquant ce que fait chaque contrôleur.

Validation :

• Est-ce que les exemples fonctionnent réellement ?
• Est-ce que la description est fidèle à ce que vous avez appris lors de l'exploration ?

Critères de réussite :

• [ ] Généré un README pour au moins un module
• [ ] Vérifié l'exactitude par rapport à vos notes d'exploration
• [ ] Identifié toute inexactitude dans le contenu généré

---

Checklist de Validation

Pour chaque documentation générée, vérifiez :

• [ ] L'objectif est exact - La description correspond-elle au comportement réel ?
• [ ] Les paramètres sont corrects - Types et descriptions correspondent au code
• [ ] Les valeurs de retour sont exactes - Ce que la fonction retourne réellement
• [ ] Les cas limites sont mentionnés - Gestion d'erreurs, vérifications de null, etc.
• [ ] Les exemples fonctionnent - Si Claude a fourni des exemples, s'exécutent-ils ?

---

Modes d'Échec Courants

Surveillez ces problèmes dans la documentation générée :

Problème	Exemple	Comment le repérer
Noms trompeurs	validateEmail vérifie seulement la présence de @	Comparer avec les assertions des tests
Effets de bord cachés	Un "getter" qui modifie aussi l'état	Lire le code réel
Cas limites manquants	Aucune mention de la gestion des null	Vérifier les chemins d'erreur dans le code
Patterns obsolètes	La doc décrit ce que ça "devrait" faire	Exécuter le code pour vérifier

---

Bonne vs Mauvaise Documentation

Mauvaise (répète le code) :

// Définit x à 5
x = 5

Bonne (explique l'intention) :

// Réessaie 3 fois car l'API externe est instable
for (let i = 0; i < 3; i++) { ... }

---

Conseils pour Réussir

1. Soyez précis dans vos demandes - "Ajoute du JSDoc aux fonctions publiques" plutôt que "documente ce fichier"
2. Incluez des exemples - Demandez à Claude de fournir des exemples d'utilisation, puis testez-les
3. Documentez le non-évident - Passez le code évident, expliquez la logique complexe
4. Commentez le "pourquoi" - L'objectif compte plus que la mécanique

---

Objectifs Bonus

Si vous finissez en avance :

1. Générer une spécification OpenAPI pour une route d'API
2. Créer un diagramme d'architecture Mermaid
3. Documenter les cas limites pour la gestion des erreurs

---

Livrables

À la fin de ce lab, vous devriez avoir :

1. Des commentaires JSDoc ajoutés à au moins 2 fonctions
2. Un README.md pour au moins un module
3. Des notes sur les inexactitudes trouvées et corrigées
4. Une compréhension de comment valider la documentation générée par l'IA

---

Prochaines Étapes

Après avoir complété ce lab, passez au Lab 1.7 : Reconnaissance Complète du Codebase - le capstone du Jour 1.