Anatomía de una especificación
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 justificó por qué la unidad de trabajo de esta serie es una funcionalidad y no el proyecto entero. Queda por resolver qué se escribe adentro de esa unidad. Hasta ahora, la especificación de la Bitácora de lecturas creció por acumulación: tres líneas en el primer post, una intención por encima en el segundo, un contrato en el tercero, un alcance en el cuarto. Cada sección llegó cuando un argumento la pidió, no porque el documento tuviera un formato decidido de antemano. Este post fija ese formato.
La especificación de una funcionalidad tiene seis partes, y cada una responde una pregunta distinta a quien la lee.
El contexto y objetivo dice para qué existe la funcionalidad y para quién. Es la capa de intención del segundo post reducida a un párrafo. Sin esta parte, el resto es una lista de comportamientos sin razón, y cuando dos requisitos chocan no queda nada con qué decidir cuál gana.
El alcance dice qué cubre el documento y qué no. La mitad que suele omitirse es la segunda, y es la que más trabajo ahorra: un lector, humano o agente, que no encuentra una funcionalidad vecina nombrada como excluida tiende a suponer que está incluida, o que queda a su criterio. Nombrar lo que queda fuera cuesta una línea por cada exclusión.
Los requisitos dicen qué tiene que cumplir el sistema, uno por línea. Cómo se escribe un buen requisito es tema de los próximos posts. Por ahora alcanza con que cada uno afirme una sola cosa que se pueda observar desde afuera.
Los criterios de aceptación dicen cómo se comprueba que cada requisito se cumple. Se parecen mucho a un test escrito en prosa, y la serie les dedica más adelante un post propio. En este alcanza con reconocer que son una parte distinta de los requisitos: el requisito afirma, el criterio permite comprobar.
Los supuestos dicen qué se da por cierto sin haberlo verificado. Escribirlos no los vuelve ciertos, pero los convierte de algo invisible en algo revisable: quien lee la spec puede objetar un supuesto, mientras que un supuesto que nadie escribió solo se descubre cuando falla.
Las preguntas abiertas dicen qué todavía no se decidió. Se distinguen de los supuestos en algo simple: un supuesto se afirma, una pregunta se reconoce como pendiente. Una pregunta abierta no es una falla del documento. Es lo que impide que alguien la resuelva en silencio, con lo primero que parezca razonable.
Falta lo que no va en ninguna de las seis. Pseudocódigo, nombres de clases o de tablas, elección de bibliotecas: todo eso pertenece a la capa de implementación que el segundo post separó. Hay una prueba práctica para decidir si una frase entra: si seguiría siendo cierta con una implementación completamente distinta, pertenece a la spec. Si deja de serlo, es diseño.
La spec de guardar un artículo ya tiene casi todo el material, pero ordenado por orden de llegada y no por función. Tiene una intención, tres requisitos, una sección de implementación que el segundo post marcó como ajena al documento, un contrato y un alcance. No tiene criterios de aceptación, ni supuestos, ni preguntas abiertas, y el alcance nombra lo que queda fuera solo dentro de un párrafo de prosa.
Reordenarla según las seis partes obliga a mirar cada cosa desde la pregunta que responde, y eso deja una consecuencia que no era visible antes. Una de las tres viñetas de la sección de implementación decía que la URL nueva se compara contra las guardadas normalizando mayúsculas y quitando la barra final. Esa frase resolvía una pregunta que la especificación nunca formuló: si dos URL que difieren solo en eso son la misma. Mientras vivió como implementación, la decisión se tomó sin que nadie tuviera que reconocer que era una decisión. En la anatomía nueva esa sección sale del documento, y la pregunta que escondía aparece donde corresponde.
# 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ó.
## 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 dejar las dos preguntas abiertas sin responderlas. Sería fácil resolverlas ahora con lo que parece razonable, y el documento quedaría más prolijo. Pero una respuesta elegida por comodidad es un requisito que nadie discutió, y la pregunta sobre las mayúsculas afecta directamente lo que el segundo requisito considera "esa URL". Queda escrita como pregunta hasta que el proyecto llegue al punto de resolverla a propósito. También cambió otra cosa sin anuncio: la frase del alcance anterior que decía que la funcionalidad se especificó el mismo día en que se implementó salió del documento. Describía cómo se escribió la spec, no qué exige del sistema, y ese dato pertenece al método, no al artefacto.
Conviene leer la versión anterior de la spec como la leería un agente al que se le encarga implementarla: contexto, tres requisitos y un contrato. Parece completa, y esa es la parte engañosa. Para implementarla hay que decidir necesariamente si dos URL que difieren en una barra final son la misma, qué guardar como título cuando la página no tiene ninguno, y si una aplicación que guarda artículos y no ofrece ninguna forma de verlos no está, en realidad, incompleta. Cada una de esas decisiones puede resultar razonable. Ninguna queda a la vista.
Es la misma familia de problema del primer post, con una diferencia. Allí la ambigüedad estaba en algo que la spec decía a medias, la URL repetida. Acá está en algo que la spec no menciona en absoluto, y por eso no hay ninguna frase sospechosa que señalar. Una revisión atenta de los tres requisitos no encuentra nada mal, porque el problema no está en lo escrito sino en lo que falta. Se descubre leyendo el código que produjo el agente, o usando el resultado y notando un comportamiento que nadie pidió.
Esta estructura tampoco es gratuita. Seis secciones para tres líneas de requisitos es una proporción que se puede sentir excesiva, y una sección con nada real que decir, un "Supuestos: ninguno" puesto para completar la plantilla, es ruido que además le enseña a quien lee a saltear secciones. La anatomía es un inventario de preguntas que conviene hacerse, no una plantilla que llenar. Cuánta de cada parte hace falta según el tipo de trabajo es una calibración que la serie trata más adelante, con sus propios criterios.
Una especificación no se completa agregando detalle, se completa respondiendo seis preguntas: para qué, hasta dónde, qué debe cumplirse, cómo se comprueba, qué se da por cierto y qué falta decidir. Las dos últimas son las que evitan que alguien más decida en silencio.
Con la estructura del documento ya fijada, el próximo post de la serie se ocupa de la tercera parte, los requisitos: qué distingue una frase como "que sea rápido" de otra que dos personas pueden leer y coincidir, sin discutir, en si el sistema la cumple.