Requisitos verificables
Seguí leyendo
Enterate del próximo post
Un mail cuando publico algo nuevo. Sin spam y te podés dar de baja cuando quieras.
Un mail cuando publico algo nuevo. Sin spam y te podés dar de baja cuando quieras.
El post anterior fijó las seis partes de una especificación y dejó la tercera, los requisitos, apenas definida: una afirmación por línea, observable desde afuera. Alcanza para ordenar el documento, pero no para saber si una línea concreta está bien escrita. Este post agrega la prueba que falta.
Un requisito es verificable si dos personas que lo leen por separado, con el mismo sistema delante, coinciden en si lo cumple. No hace falta que el sistema exista ni que lo cumpla. Hace falta que el desacuerdo, si aparece, trate sobre el sistema y no sobre lo que la frase quiso decir.
La frase "guardar tiene que ser rápido" no pasa la prueba. Quien la comprueba con una buena conexión ve la página cargada en un segundo y la da por cumplida. Quien la comprueba con una conexión lenta espera cuatro y la da por incumplida. Ninguno se equivocó: la frase nombra una cualidad y deja que cada lector ponga su propio umbral. La discusión que sigue no es sobre el sistema sino sobre qué significaba "rápido", y ocurre tarde, cuando ya existe código que defender.
La versión verificable no cambia la intención, le agrega una medida: cuánto se considera rápido, medido desde dónde hasta dónde y bajo qué condiciones. Con esos tres datos, dos personas con un cronómetro llegan al mismo veredicto.
Hay un segundo modo de fallar, menos visible. "El guardado usa una caché de títulos" es preciso y se puede comprobar, pero describe un mecanismo, no algo que quien usa el sistema pueda observar. Un sistema puede cumplirlo y ser inútil, o incumplirlo y funcionar perfectamente. Es la mezcla de capas que el segundo post separó, ahora dentro de una sola línea. Una pregunta práctica alcanza para detectarlo: qué vería alguien desde afuera si el requisito se cumple, y qué vería si no. Si la respuesta es que no vería nada, la línea no es un requisito.
Dos aclaraciones evitan malentendidos. Verificable no significa verificado: la prueba se aplica al texto, antes de que exista nada que ejecutar. Y verificable no significa numérico: hay requisitos que se comprueban con un juicio contra criterios escritos, y la serie los trata más adelante. Lo que sí exige la prueba es que alguien decida algo. Una medida elegida puede resultar equivocada, pero un número equivocado y comprobable se corrige en cinco minutos, mientras que una frase acertada e incomprobable no se puede distinguir de una errónea.
Los tres requisitos de guardar-articulo.md pasan la prueba, con una salvedad. "Un artículo se guarda a partir de su URL" se comprueba entregando una URL y mirando si el artículo existe. "Además de la URL, se guarda el título de la página y la fecha en la que se guardó" también, y este caso aclara qué exige la prueba y qué no. Un sistema que guarda el día y otro que guarda el instante exacto cumplen los dos la línea, y dos lectores coincidirían en ambos casos. Precisar el formato de la fecha no la haría más verificable: solo empujaría una decisión de implementación hacia la spec. Una línea no necesita ser más precisa que la diferencia que importa.
La salvedad es el segundo requisito. Avisar que una URL ya existe es comprobable, pero "esa URL" tiene un límite conocido: la primera pregunta abierta del documento, que plantea si dos URL que difieren solo en una barra final son la misma. Ahí dos lectores discrepan hoy, y la spec lo dice en voz alta en lugar de esconderlo. Es lo que hace una pregunta abierta con la verificabilidad: marca el borde hasta donde el documento ya permite comprobar.
Falta un requisito que el documento todavía no tiene. Guardar un artículo incluye pedirle el título a la página, y eso hace depender la operación de algo que el sistema no controla. Es el lugar donde aparece, casi sin falta, la frase de más arriba. Por eso el requisito nuevo se escribe primero como la escribiría cualquiera y después como pide la prueba.
La primera versión de la línea nueva, tal como surge sin pensarlo:
Guardar tiene que ser rápido.
Y la spec con la versión que pasa la prueba. Solo cambia ## Requisitos, que gana un cuarto requisito; el resto del documento queda igual que en el post anterior.
# Guardar un artículo
## Contexto y objetivo
Quien usa la Bitácora encuentra artículos que quiere leer más tarde y no
tiene tiempo de leer en el momento. Necesita guardarlos sin perder el
título ni la referencia de dónde los encontró, y sin terminar con el
mismo artículo guardado dos veces por error.
## Alcance
Dentro: guardar un artículo a partir de su URL.
Fuera: etiquetar artículos, marcarlos como leídos, borrarlos, ver la
lista de artículos guardados y armar el resumen semanal. Cada una es
una funcionalidad distinta, con su propia especificación.
## Requisitos
- Un artículo se guarda a partir de su URL.
- Si esa URL ya fue guardada antes, no se guarda de nuevo: se avisa que
ya existe.
- Además de la URL, se guarda el título de la página y la fecha en la
que se guardó.
- Si la página responde en menos de 2 segundos, quien guarda recibe el
resultado (artículo guardado o aviso de que ya existe) en menos de 3
segundos desde que lo pide.
## Criterios de aceptación
Vacía a propósito: se completa cuando la serie llegue a este tema.
## Supuestos
- Quien guarda es una única persona por instalación: no hay cuentas ni
artículos de otras personas.
- La URL apunta a una página pública, que se abre sin iniciar sesión.
## Preguntas abiertas
- ¿Dos URL que difieren solo en mayúsculas o en una barra final cuentan
como la misma?
- ¿Qué se guarda como título si la página no responde o no tiene título?
## Contrato
Precondición
La URL que llega es un texto no vacío.
Poscondición
Si la URL no estaba guardada antes de esta llamada, existe un artículo
nuevo con esa URL, su título y la fecha de guardado.
Si la URL ya estaba guardada, no se crea ningún artículo nuevo y el
sistema avisa que ya existe.La decisión menos obvia es la condición del principio. Sin ella, el requisito exigiría tres segundos aunque la página tarde diez en contestar, algo que el sistema no puede cumplir y que ninguna implementación correcta lograría. Con la condición, el caso de la página lenta queda fuera del requisito a propósito, y cae dentro del borde de la segunda pregunta abierta, que hoy dice "no responde" sin dar un plazo. La medida ahora existe y podría, más adelante, completar esa pregunta. Los dos números son elecciones de quien escribe: dos segundos para la página y uno de margen para el resto. Tampoco se resolvió qué se guarda si la página tarda más, porque esa decisión sigue sin tomarse y merece tomarse a propósito.
Con la frase vaga, un agente que implementa la spec pide el título de la página, espera la respuesta y guarda. En la máquina donde trabaja, con la página cargando en medio segundo, el resultado se siente inmediato y se informa como cumplido. La revisión no tiene nada que señalar, porque la frase se cumple bajo casi cualquier lectura.
El problema aparece en uso. Una página que tarda doce segundos deja a quien guarda esperando doce, y el reclamo, "esto no es rápido", abre una discusión de gusto: doce segundos es mucho para quién, y desde cuándo. Mientras tanto, la decisión de cuánto esperar antes de rendirse se tomó igual, en el código, por quien escribió la llamada de red o, más probablemente, por el plazo que la biblioteca trae por defecto, que puede ser de varios minutos o no existir. Es una decisión de producto tomada sin que nadie la reconociera como tal, la misma familia de problema que el post anterior mostró con la barra final de la URL.
La verificabilidad también tiene un costo. Exige una medida, y a veces no hay una medida honesta. "Fácil de usar" se resiste a un número, y forzar uno que nadie va a medir, algo como "el 95 % de las personas lo entiende", agrega apariencia de precisión sin agregar ninguna comprobación. Un número inventado para completar la forma es peor que una pregunta abierta que admite no saber. Para esos requisitos existe otro tipo de verificación, con criterios escritos y ejemplos de referencia, que la serie trata en su momento.
Un requisito está bien escrito cuando dos personas que lo leen por separado pueden discrepar sobre el sistema, pero no sobre el significado de la frase. Para lograrlo hay que decidir una medida, y decidirla es parte del trabajo, no un trámite.
La prueba dice si una frase se puede comprobar, pero no cómo escribirla para que salga así cada vez. El próximo post presenta cinco plantillas de frase, conocidas como EARS, que fijan de antemano dónde van el disparador, la condición y la respuesta.