Como documentar la arquitectura de software

Escrito por Diego Gomez

Sábado 01 de Noviembre de 2008 08:45

Por lo general, se entiende por documentar software como solo hacer el Diagrama de Clases en el diseño. Por supuesto que documentar la arquitectura de software no es solo eso, y muchas veces los arquitectos no documentan los proyectos y no acompañan a los desarrolladores en el proceso de documentación. Por lo que ví hasta el momento, los arquitectos no se involucran de la forma adecuada en cada proyecto y solo definen de vez en cuando algo de la arquitectura general y luego se dedican a otras cosas...

Empecemos con la definición teórica de IEEE en su clásica guía de recomendaciones IEEE 1471 (y también se encuentra en el libro "Software Architecture in Practice, 2nd Edition"): "La arquitectura de un sistema de software es la estructura o estructuras del sistema, que incluye elementos de software, las propiedades externamente visibles de esos elementos y la relación entre ellos."
Evidentemente, esta definición debe ser detallada, porque de lo contrario estamos en lo mismo :-).
Cuando hablamos de estructuras estamos hablando de estructuras estáticas y dinámicas. Las estructuras dinámicas definen la forma en que el sistema funciona en tiempo de ejecución, entonces sólo un diagrama de clases no resolvería ese punto.

Cuando hablamos de propiedades externamente visibles estamos hablando de las interaciones de un elemento o un sistema con su entorno exterior. Puede ser el flujo de información de entrada y de salida, la forma en que el elemento responde a los estímulos externos y el contrato (la interfaz) de dicho elemento.

Otra definición importante, que encontramos en el excelente libro "SSoftware Systems Architecture: Working with stakeholders using viewpoints and perspectives" es que la arquitectura de software debe ser dirigida por las necesidades de las personas que participan en el proyecto: clientes, usuarios, el departamento de IT, soporte, producción, operación, etc. La arquitectura de software no puede ser pensada sin el contexto de los stakeholders. Esto puede parecer obvio, pero muchos sistemas por allí se realizan sin la debida atención a las necesidades de las personas involucradas. He visto un montón de gente escoger una arquitectura por ser la ola del momento, sin preguntarse profundamente si aquello satisface las necesidades del negocio. En resumen: Las arquitecturas debe ser creadas sólo para satisfacer las necesidades de los stakeholders. Una buena arquitectura es aquella que cumple con éxito los objetivos y las necesidades de sus stakeholders.

Otra interesante definición, procedente de RUP, es que la arquitectura de software es un conjunto de decisiones cruciales que restringen las consideraciones de diseño y programación y que tienen un alto impacto para ser revertidas. Por ejemplo, si se determina que el sistema se hará en JEE utilizando Struts 2, entonces los desarrolladores no pueden desarrollar el sistema utilizando la Spring MVC. Por otra parte, el cambio de Struts 2 a Spring MVC, por ejemplo, traería un alto impacto para la capa WEB de la aplicación.

Por otra parte, es el papel del arquitecto explicar los motivos detrás de la elección de determinados elementos arquitectónicos en detrimento de los demás. También la realización de análisis "buy vs. build", es decir, comprar o utilizar un componente de código abierto en lugar de construirlo desde cero. O construir algo desde cero considerando que en el mercado existe ya algo listo para su uso.

El arquitecto también debe hacer hincapié y centrarse en los atributos de calidad del sistema, los llamados requisitos no funcionales. Debe verificar las necesidades de los stakeholders con respecto al rendimiento, escalabilidad, mantenimiento, seguridad, internacionalización, entre otros.

Para tener una idea de las diferentes "áreas" las cuales un arquitecto debe hacer frente, podemos volver al libro "Software Systems Architecture". El principio inicial definido por los autores es que "no se puede capturar las necesidades funcionales y las propiedades de calidad de un sistema complejo en un solo modelo comprensible". A partir de ahí es que surge la necesidad de lo que ellos llaman Visiones y Perspectivas. RUP posee el 4+1 View Model. El IEEE establece un poco más. Algunos de estos puntos de vista: Informativo, Concurrencia, Desarrollo, Despliegue, Operativo y Funcional. Ya algunas de las perspectivas importantes son: Seguridad, Rendimiento y Escalabilidad, Disponibilidad y Resiliencia, Evolución, Accesibilidad, Internacionalización, Localización, Reglamentación y Usabilidad.

Ahora puede surgir una duda que es común: debemos documentar estas cosas? Donde las documentamos?

Por supuesto, no hay una respuesta genérica. Como todo en la Ingeniería del Software ... depende! Un sistema super simple no necesita ninguna documentación. Un sistema super complejo (como un satélite o un Boeing) tendrá una más amplia documentación.

Sin embargo, para los casos que estamos más acostumbrados a trabajar (sistemas y aplicaciones empresariales y corporativas) se recomienda tener al menos un "documento de arquitectura de software". No precisae ser un documento de Word en sí. Puede ser una página de Wiki, una hoja A4, una cartulina, etc.

Recomiendo que este documento sea breve y que tenga solamente la información esencial, tal como:

Elementos y los principales componentes del sistema.
Capas del sistema.
Mecanismos arquitecturales necesarios para el sistema.
Tecnologías elegidas para hacer frente a cada capa y el mecanismo y la motivación detrás de estas opciones.
Componentes comprados o de código abierto que se utilizarán y la forma en que se tomó la decisión.
Descripción de los principales patrones de diseño utilizados y por qué la elección.
Definición de la forma en que el acceso a sistemas externos y / o legados.

Además, algunos equipos pueden sentir la necesidad de desarrollar diagramas UML. Estos diagramas relacionados con la arquitectura y el diseño estarán en el modelo de diseño (si usted usa RUP en el proceso de desarrollo). El equipo puede utilizar los diagramas de clase, actividad, secuencia, estados, componentes y despliegue para facilitar la comprensión visual de los elementos y sus relaciones (conforme la definición de arquitectura de software por la IEEE).

Reforzando y recordando siempre que las actividades relacionadas a la arquitectura se hacen de manera iterativa e incremental. Por lo tanto, cuidado de no caer en el modelo en cascada y estar durante largos períodos de tiempo tan sólo escribiendo el documento de la arquitectura. Un buen y verdadero arquitecto es aquel que pone las manos en la masa y prueba con código y con test que su arquitectura realmente va a satisfacer las necesidades de los stakeholders!!! Además, el arquitecto debe ser una persona sociable e ir detrás de los stakeholders para validar sus decisiones arquitectónicas más importantes.

Bueno, esto es sólo una punta de introducción sobre la cuestión. Si alguien tiene más preguntas puede dejar un comentario en este artículo!