Metodología Ágil: Documentación Arquitectónica y Diseño.

Metodología Ágil: Documentación Arquitectónica y Diseño.

Hay algunas preguntas que se plantean (en desarrollo de software) en lo referente a la Arquitectura y el Diseño de software en la filosofía ágil tales como: ¿Es necesaria alguna documentación de arquitectura trabajando con metodologías Ágiles? ¿Es necesario el diseño trabajando con metodologías Ágiles?
Hay quienes contestan (en un marco de agilidad) que no, no es necesario: el código es el diseño.

El código es el diseño

Existe una idea, en la agilidad de software, de diseño minimalista y evolutivo que dice que “el código fuente es el diseño” [Reeves 1992][Ruth & Bredemeyer 2002]; y según esta idea (en extremo) se puede ver al código fuente como el resultado final y visible del diseño, y en dónde quedan plasmados todos los aspectos de éste (no es necesario nada más). Esta idea es llevada al extremo con algunos practicantes de algunas metodologías ágiles, en donde se considera que el diseño no existe como etapa de desarrollo ni como generador de algún artefacto formal y tampoco hay alguna documentación que esboce la arquitectura del sistema. Sólo se tiene en cuenta el diseño como algo informal, útil para transmitir ideas entre desarrolladores. La justificación es que es engorroso mantener documentación y que con el refactoring continuo, el buen diseño se va encontrando de a poco en forma emergente. También hay una mala interpretación de: "Software funcionando sobre documentación extensiva" [Manifiesto Ágil]. Priorizar el producto en lugar de la "documentación extensiva" no implica eliminar la documentación.

El código NO es el diseño

La crítica a lo anterior es que "el código no es el diseño". Esta difundida una creencia errónea de que la agilidad implica no documentar [UNTREF 2014]. La idea de que en el código se refleja toda decisión de diseño [UNTREF 2014]. Pues no, el el código no es el diseño, porque solamente nos muestra una vista de éste (la vista de código), mientras también existe, entre otras, la dinámica y la integración. También hay varios modelos, por ejemplo: el de componentes, el de análisis, el de casos de uso, etc. Decir que el código fuente es el diseño es como decir que el edificio terminado es su diseño [Anacleto 2005] y no es necesario nada más para entenderlo. Con solo el código podemos ver la estructura interna del código y extraer información, pero no podemos ver la estructura interna de los componentes que usa, así como tampoco nos es práctico extraer información a partir de la estructura, entender la integración, la dinámica de componentes, la justificación de su estructura y el funcionamiento del todo. La abstracción es necesaria para comprender el todo paulatinamente y de manera efectiva. No significa mantener alto formalismo en la especificación, no significa mantener grandes y engorrosos documentos, no significa planificar y preveer todo el diseño en forma previa; sino que significa no carecer de alguna documentación de arquitectura de sistemas, no prescindir de hacer arquitectura y diseño; tener la documentación minima y necesaria para entender la arquitectura del sistema de forma ágil (y no perder tiempo enorme de investigación haciendo ingeniería inversa para entender el sistema); significa plasmar los lineamientos arquitectónicos durante todo el desarrollo para posibilitar la emergencia de una buena arquitectura; y significa hacer ingeniería. El buen diseño NO surge necesariamente de un grupo de personas trabajando o haciendo artesanía. El buen diseño SI emerge del trabajo en equipo de profesionales motivados altamente capacitados haciendo ingeniería.

Por otro lado, se puede argumentar que el código es un nivel intermedio de abstracción y modelado y el de arquitectura o diseño arquitectónico es superior en niveles de diseño de software. Por lo que solo con el código no alcanza para modelar el sistema y entenderlo. Shaw and Garlan [Shaw 1996] proponen tres niveles de modelado y comprención: Máquina, Código y Arquitectura [Malveau 2004]. Según estos niveles: "el código no es el diseño".

Documentar en forma Ágil

La agilidad implica un balance intermedio:

"ni el extremo de plasmar todas las decisiones en documentos, ni el otro de creer que el código puede mantener toda la información necesaria" [UNTREF 2014].

El diseño y su documentación debe permitir la colaboración, el refactoring (con documentos vivos) y la simplicidad (documentos minimalistas y eficaces en didáctica) entre otras características. Se debería poder plasmar la justificación de por qué se tomaron siertas decisiones ya sea en documentos o en comentarios en el código.

El nacimiento del documento de arquitectura, en metodologías ágiles, puede ser al inicio de las iteraciones o al de una épica. En metodología XP se usa el "Spike de Arquitectura" que genera la "Metáfora del sistema" como input de la etapa de "planificación de versiones". Esta "Metáfora del sistema" irá evolucionando en los sucesivas iteraciones. En Scrum se puede hacer algo semejante, se puede tener un sprint 0 para generar o modificar esta "Metáfora del sistema" que luego se irá modificando en los restantes sprints. También el documento puede surgir o ser modificado en stories técnicas de investigación o específicas de diseño.

Documentación Arquitectónica

Lo ideal de una documentación arquitectónica (Documento de Arquitectura de Software SAD) es que sea minimalista, didáctica, versionable (el SAD es un documento vivo [DSA 2010]), accesible e indexada a un código específico (o revisión de código fuente). En este sentido se pueden realizar diferentes implementaciones. 

Documentación con LaTeX

Particularmente me inclino por que haya una documentación versionable básica en el mismo lugar donde se encuentra el código. Por ejemplo en una carpeta "doc". Para que sea versionable se puede usar código html o LaTeX. Algunos pueden decir que es dificil que todos sepan html o LaTeX para editar un documento, pero no es necesario que todos sepan, con que sepan los arquitectos y/o desarrolladores alcanza, Y los mismos son ingenieros y técnicos que deberían estar capacitados para que la edición de un html o LaTex sea algo trivial.

Se puede tener alguna plantilla básica o "documento base" [DSA 2010] de un SAD base y trabajar sobre él. Por ejemplo aquí hay tres documentos base:

• Plantilla 1: SAD LaTeX template [DSA 2010] (repo GIT).
• Plantilla 2: SAD basic LaTeX template (repo GIT).
• Plantilla 3: SAD básico en español (repo GIT). 

     (Repositorio GIT: https://github.com/dariopalminio/latex.templates)

Por convensión sería más apropiado que los documentos esten en ingles, para que sean didácticos puede llevar a escribir simple y claro; pero también se podría preferir la documentación en español (principalmente si los stakeholders que tiene acceso a su lectura son españoles).

Referencias:

[Ruth & Bredemeyer 2002] Malan, Ruth, and Dana Bredemeyer, "Less is More with Minimalist Architecture", published in IEEE's IT Professional, September/October 2002.

[Reeves 1992] Code as Desgin, Jack W. Reeves, 1992 Disponible en URL: http://www.developerdotstar.com/mag/articles/reeves_design_main.html

[Anacleto 2005] El rol de la arquitectura de software en las metodologías ágiles. Lic. Valerio Adrián Anacleto. Epidata Consulting S.R.L.- Buenos Aires, Argentina. Diciembre de 2005. Disponible en URL: http://www.epidataconsulting.com/tikiwiki/tiki-read_article.php?articleId=28#El_c_digo_NO_es_el_dise_o

[DSA 2010]
Documenting Software Architectures: Views and Beyond. Paul Clements (Author), Felix Bachmann  (Author), Len Bass (Author), David Garlan (Author), James Ivers (Author), Reed Little (Author), & 3 more. October 15, 2010.
https://connectopensource.atlassian.net/wiki/pages/viewpage.action?pageId=10584112

https://wiki.sei.cmu.edu/sad/index.php/Software_Architecture_Documentation_Template

[UNTREF 2014]

Construcción de software: una mirada ágil. Nicolás Paez, Diego Fontdevila, Pablo Suárez, Carlos Fontela, Marcio Degiovannini, Alejandro Molina. Universidad Nacional de Tres de Febrero (UNTREF), 2014.

[Simon Brown 2915]
Simple Sketches for Diagramming your Software Architecture
Disponible en URL: http://www.methodsandtools.com/archive/softwarearchitecturesketches.php

[Adrián Paredes 2012]
Documento de Arquitectura de Software. 2012.
Disponible en URL: http://elblogdelfrasco.blogspot.com.ar/2012/02/documento-de-arquitectura-de-software.html

[Manifiesto Ágil]
Manifiesto por el Desarrollo Ágil de Software. URL: http://agilemanifesto.org/iso/es/

[Malveau 2004]

Software Architect BOOTCAMP. The completely updated “field manual” for becoming a better software architect! Raphael Malveau, Thomas J. Mowbray Ph.D. Prentice All, Second Edition, 2004 Pearson Education Inc.ISBN: 0-13-141227-2. Disponible en URL: http://users.atw.hu/softarchcamp/