Los ingenieros de software somos autores y escribimos historias para que otros compañeros las lean después.

Sí; habéis leído bien.

Si no, ¿para qué existe la etiqueta @author en Javadoc?

Tened esto en cuenta cuando escribáis la próxima línea de código, y quien lo lea os lo agradecerá.

Clean code

¿Os suenan estas ideas? Efectivamente, parte de ellas están extraídas del primer capítulo de uno de mis libros favoritos: Clean code. Un “must” que todos deberíamos incluir en nuestra biblioteca. ¿Os lo habéis leído? Si no, ya sabéis: al “backlog” de libros a leer. Si lo habéis hecho ya, dadle otra vuelta de vez en cuando. Yo aprendo algo nuevo cada vez que lo hago.

Bueno, vamos al turrón, que me despisto.

Lo que quiero compartir con vosotros en este post es un patrón muy sencillo. Se trata del “patrón builder”, cuyo principal objetivo es ayudar a que tu código cuente una historia. Aunque se utiliza principalmente en el código de test, que documenta el comportamiento de tu aplicación, debes utilizarlo también en el código de la aplicación.

Si buscamos la definición de este patrón en internet, encontraremos algo así: “el patrón builder permite construir objetos complejos utilizando objetos simples y especificandolos por pasos”. Es decir, tal y como se muestra en la siguiente imagen, permite construir cosas complejas a partir de piezas más sencillas y combinadas entre ellas.

House
Veamos un ejemplo para entenderlo mejor:

Pensemos en un módulo que evalúa el riesgo de realizar una transacción calculando el tipo de autenticación requerida para ejecutarla o denegando la operación si se detecta que se trata de una operación con riesgo alto.

Para el siguiente requisito:

Dado un cliente que ha cambiado su número de teléfono móvil hace menos de treinta días, cuando intenta realizar una transferencia de más de trescientos euros diarios acumulados a una cuenta corriente no frecuente, entonces se deniega la operación por tener un riesgo alto de fraude.

Tenemos el siguiente código fuente resultante de un test que verifica este requisito utilizando el patrón “builder”:

¡Increíble! ¿Cómo lo veis? ¿Cuenta el código realmente la historia que hemos descrito? Parece que sí…

Repasemos los pasos. En primer lugar, hemos descrito nuestro requisito utilizando un ejemplo concreto para evitar la ambigüedad inherente del lenguaje natural.

En segundo lugar, este ejemplo sigue una gramática o DSL (Domain Specific Language) pensada para documentar pruebas llamada Gherkins. Me reservo otro post para hablar largo y tendido de esta gramática, que resulta clave a la hora de practicar BDD 😉

Finalmente, sólo queda comentar brevemente que cada requisito se define describiendo tres cualidades:

  • Los “givens” (dado): Para determinar el estado del sistema antes de la interacción.
  • Los “whens” (cuando): Describen la interacción.
  • Los “thens” (entonces): Permiten comprobar los resultados.

Tener el requisito, n formato Gherkins, nos va a ayudar mucho a la hora de escribir las pruebas automáticas puesto que define claramente el contexto, las acciones y los resultados que deben comprobarse. Para fijar el contexto suele ser necesario crear muchos objetos y en ocasiones bastante complejos. Es aquí donde podemos utilizar la potencia del “patrón builder”. Se trata de replicar con código y por partes las distintas secciones de nuestro requisito. El objeto builder se devuelve siempre a sí mismo en cada uno de los métodos salvo en el método “build” que crea y devuelve el objeto que construye, ocultando así toda la complejidad necesaria y ayudándonos a mejorar enormemente la legibilidad del código. Veamos un ejemplo:

¿Cómo os habéis quedado? ¿Os creéis ya que el código fuente puede contar una historia? Pues no sólo puede, sino debe. En este caso, el código de test sirve al mismo tiempo de documentación, puesto que es un fiel reflejo de los requisitos originales.

¿Necesitaréis más documentación que ésta en vuestro proyecto?  Es cierto que muchas aplicaciones tiene un código que no te servirá como documentación, pero eso no quiere decir que no se pueda. Si tu código fuente cuenta una historia ;-), no la necesitarás.

Gracias por leerme,

José San Román A. de Lara