Un LEEME con una función inventada
Pides a un asistente que documente tu módulo y el LEEME queda precioso. Meses después, alguien llama a una función que ese texto describe y que nunca existió. Documentar con un asistente es rápido, pero el texto puede decir cosas falsas con mucha seguridad.
Aquí aprendes a pedir documentación útil y a comprobarla contra el código.
Al final de esta lección
Nota
Puedo hacer que un asistente escriba documentación y comprobarla contra el código.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| Documentación | el texto que explica cómo se usa el código | |
| Afirmación | cada cosa concreta que dice un texto | change(paid, due) |
| Respaldada | que el código confirma esa afirmación | |
| Comentario de qué | un comentario que repite lo que ya dice el código | |
| Comentario de por qué | un comentario que da una razón que el código no muestra |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Un comentario explica el porqué, no el qué
El código ya dice qué hace. Un comentario que lo repite no aporta nada y envejece mal. Un comentario de por qué da la razón que no se ve: de dónde sale una regla o por qué un borde incluye el 3.
Los asistentes escriben muchos comentarios de qué. Pide que solo escriba comentarios de por qué, y borra los demás.
Comentarios de qué y de por qué
| Comentario | Qué dice | Tipo |
|---|---|---|
| // suma 1 a i | Lo que ya dice la línea | De qué: sobra |
| // devuelve el total | Lo que ya dice el nombre | De qué: sobra |
| // con 3 artículos ya cuenta como pack | La regla de la tienda | De por qué: útil |
| // en céntimos para no usar decimales | La razón de un diseño | De por qué: útil |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Cada afirmación de un texto se puede comprobar
Un LEEME hace afirmaciones: este nombre existe, esta función recibe dos parámetros. El asistente las escribe con la misma seguridad cuando acierta y cuando se inventa algo.
Para cada una, pregunta si el código la confirma. Una afirmación que el código confirma está respaldada. Las demás se corrigen o se borran.
Una petición posible
Esta es una petición posible, no la única. «Escribe un LEEME breve para caja.js. Una línea por función, con sus parámetros. Solo funciones que existan en el archivo. Nada de comentarios que repitan el código.»
Cuando llegue el texto, no lo lleves al repositorio todavía. Compruébalo primero.
Un ejemplo escrito a mano
El código y el LEEME de abajo los escribimos nosotros, a mano. Ningún asistente los escribió. El LEEME lleva dos afirmaciones falsas a propósito.
Los botones escriben archivos en la carpeta demo-docs de tu proyecto. No tocan el programa de la caja.
Crear la carpeta de la demostración
docker exec -w /home/node/project agent mkdir -p demo-docsSe muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Escribir el código
docker exec -w /home/node/project agent sh -c "printf '%s\n' '// Funciones de una caja pequeña. Los precios van en céntimos.' 'function total(items, prices) {' ' let sum = 0;' ' for (const item of items) sum = sum + prices[item];' ' return sum;' '}' 'function change(paid, due) {' ' return paid - due;' '}' 'function format(pence) {' ' return (pence / 100).toFixed(2) + \" EUR\";' '}' 'module.exports = { total, change, format };' > demo-docs/caja.js"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Escribir el LEEME
docker exec -w /home/node/project agent sh -c "printf '%s\n' '# Caja' 'Una caja pequeña que suma una compra y da el cambio.' '- total(items, prices): suma el precio de cada artículo.' '- change(paid, due): devuelve el cambio al cliente.' '- format(pence): escribe un precio en euros.' '- totalWithDiscount(items, prices): aplica el descuento de socio.' '- change(paid): devuelve el cambio de un billete de 5 euros.' > demo-docs/LEEME.md"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Escribir el comprobador, parte 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const lib = require(\"./caja\");' 'const fs = require(\"fs\");' '' 'const lines = fs.readFileSync(\"demo-docs/LEEME.md\", \"utf8\").split(\"\n\");' 'for (const line of lines) {' ' if (line.startsWith(\"- \") === false) continue;' ' const open = line.indexOf(\"(\");' ' const close = line.indexOf(\")\");' ' const name = line.slice(2, open);' ' const inside = line.slice(open + 1, close).trim();' ' const words = inside === \"\" ? 0 : inside.split(\",\").length;' ' const code = lib[name];' > demo-docs/comprobar.js"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Escribir el comprobador, parte 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' ' if (typeof code === \"function\" && code.length === words) {' ' console.log(\"ok \" + name + \" (\" + words + \")\");' ' } else if (typeof code === \"function\") {' ' console.log(\"NO \" + name + \": el código tiene \" + code.length + \" parámetros y el texto \" + words);' ' } else {' ' console.log(\"NO \" + name + \": no existe en el código\");' ' }' '}' >> demo-docs/comprobar.js"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Comprobar el LEEME contra el código
docker exec -w /home/node/project agent node demo-docs/comprobar.jsSe muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Ejemplo resuelto: cinco afirmaciones
| Afirmación | Qué dice el código | Resultado |
|---|---|---|
| total(items, prices) | Existe con 2 parámetros | ok |
| change(paid, due) | Existe con 2 parámetros | ok |
| format(pence) | Existe con 1 parámetro | ok |
| totalWithDiscount(items, prices) | No existe | NO |
| change(paid) | Tiene 2 parámetros | NO |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Un error frecuente
Advertencia
Mucha gente cree que un texto bien escrito es un texto correcto. El LEEME de ejemplo se lee con soltura y dos de sus cinco líneas no son ciertas. Una buena redacción no prueba nada. Solo el código dice qué es verdad.
Para ir más lejos: tu propio módulo
En el laboratorio, escribe una función nueva que no sea el arreglo de la caja, que es la tarea del laboratorio. Por ejemplo, una que sume el precio de dos manzanas con un descuento.
Pide al agente su documentación con la petición de arriba. Antes de aceptarla, comprueba cada nombre y cada parámetro contra el código.