Une documentation qui cite une fonction absente
Un assistant de code écrit une documentation (un fichier LISEZMOI et des commentaires) en quelques secondes. Elle est claire et bien rédigée.
Elle peut aussi décrire une fonction qui n’existe pas, ou un comportement que le code n’a pas. Cette leçon apprend à demander une documentation à un assistant puis à la comparer au code.
À la fin de cette leçon
Remarque
Je peux faire écrire une documentation par un assistant et la comparer au code.
Mots-clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| Documentation | le texte qui dit comment se servir du code | |
| Commentaire | une note dans le code, pour la personne qui le lit | |
| Affirmation | une phrase de la documentation qu’on peut vérifier | |
| Nom cité | un nom de fonction écrit dans la documentation | vider(panier) |
| Exemple lancé | un exemple de la documentation qu’on exécute vraiment |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Un commentaire dit pourquoi, pas quoi
Un commentaire qui répète le code n’apprend rien : « ajoute 1 au compteur » est déjà dans la ligne. Un bon commentaire dit pourquoi le code est ainsi.
Les assistants écrivent volontiers le premier genre. Demandez donc : « n’écris un commentaire que là où le pourquoi n’est pas évident, et dis le pourquoi ».
Exemple travaillé : deux commentaires pour une ligne
| Ligne de code | Commentaire qui dit quoi | Commentaire qui dit pourquoi |
|---|---|---|
| numero = numero + 1 | Ajoute 1 au numéro | Les lignes se comptent à partir de 1, comme dans un éditeur |
| if (un === article) continue; | Passe si c’est l’article | On garde tous les autres articles, y compris les doublons |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une demande possible
Voici une demande possible : « Écris un LISEZMOI pour code.js à partir du code seul. N’écris que ce que le code fait. Pour chaque fonction, donne un exemple que je pourrai lancer. »
Ce que l’assistant renvoie change d’une fois à l’autre. Chaque nom de fonction et chaque phrase sur un comportement est une affirmation à vérifier.
Écrire le code du panier
docker exec -w /home/node/project agent sh -c "mkdir -p demo-docs && printf '%s\n' '// Fonctions du panier. Chaque fonction rend un nouveau panier.' 'function ajouter(panier, article) {' ' return panier.concat([article]);' '}' 'function retirer(panier, article) {' ' const reste = [];' ' for (const un of panier) {' ' if (un === article) continue;' ' reste.push(un);' ' }' ' return reste;' '}' 'function nombre(panier) {' ' return panier.length;' '}' 'module.exports = { ajouter, retirer, nombre };' > demo-docs/code.js"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Écrire une documentation à vérifier
docker exec -w /home/node/project agent sh -c "mkdir -p demo-docs && printf '%s\n' '# Panier' 'Un panier est une liste d’articles.' 'ajouter(panier, article) rend un nouveau panier avec l’article en plus.' 'retirer(panier, article) rend un nouveau panier sans l’article.' 'vider(panier) rend un panier vide.' 'compter(panier) rend le nombre d’articles.' > demo-docs/LISEZMOI.md"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Écrire le vérificateur de noms
docker exec -w /home/node/project agent sh -c "mkdir -p demo-docs && printf '%s\n' 'const fs = require(\"fs\");' 'const code = require(\"./code.js\");' 'const noms = [];' 'for (const ligne of fs.readFileSync(\"LISEZMOI.md\", \"utf8\").split(\"\n\")) {' ' const trouves = ligne.match(/[a-z_]+\(/g);' ' if (trouves === null) continue;' ' for (const un of trouves) noms.push(un.slice(0, un.length - 1));' '}' 'let manques = 0;' 'for (const nom of noms) {' ' const existe = typeof code[nom] === \"function\";' ' if (existe === false) manques = manques + 1;' ' console.log((existe ? \"ok : \" : \"manque : \") + nom);' '}' 'console.log(manques + \" nom(s) cites sur \" + noms.length + \" sont absents du code\");' > demo-docs/verifier-doc.js"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Chercher chaque nom cité dans le code
docker exec -w /home/node/project/demo-docs agent node verifier-doc.jsAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Lancez les exemples, ne les croyez pas
Un nom qui existe ne dit pas que la phrase est vraie. La documentation dit que retirer rend un nouveau panier. Le vérifier, c’est appeler la fonction et regarder aussi le panier de départ.
Lancez chaque exemple de la documentation. Un exemple qui ne se lance pas, ou qui donne autre chose, est une faute de la documentation.
Lancer l’exemple de retirer
docker exec -w /home/node/project/demo-docs agent node -e "const c = require(\"./code.js\"); const p = [\"a\", \"b\"]; console.log(JSON.stringify(c.retirer(p, \"a\")), JSON.stringify(p))"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Une erreur fréquente
Attention
Beaucoup pensent qu’une documentation bien écrite est une documentation juste. Le style n’est pas une preuve. Un LISEZMOI soigné peut décrire une fonction absente. Vérifiez chaque nom et lancez chaque exemple avant de le publier.
Exemple travaillé : quatre noms cités
| Nom cité | Dans le code | Affichage |
|---|---|---|
| ajouter | oui | ok : ajouter |
| retirer | oui | ok : retirer |
| vider | non | manque : vider |
| compter | non, la fonction s’appelle nombre | manque : compter |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Plus loin : essayer sur un autre fichier
C’est le bon moment pour essayer ces idées sur un autre travail. Ne touchez pas au bogue du labo, qui est le travail de la leçon 6. Demandez plutôt de documenter une fonction de shop.js.
Relevez chaque nom qu’il cite, cherchez-le dans le code, puis lancez ses exemples. Notez ce que la documentation affirmait sans que le code le fasse.