Me uní a la mitad de un proyecto de tamaño mediano, que ya lleva varios años. Uno de los problemas es que el documento que describe la arquitectura nunca fue escrito. Ahora se me asignó una tarea para escribir la descripción de la arquitectura.

Durante el tiempo que trabajé en este proyecto, reuní toda la información que necesitaba para escribir el documento. Como también agregué algunas características, identifiqué algunas piezas de código, que claramente están rompiendo la arquitectura como se describe.

Por ejemplo, se suponía que la GUI era una capa delgada, sin lógica empresarial. Eso es lo que me dijeron. La implementación contiene mucha lógica.

Mi jefe me asignó la tarea, escribir el documento que describe la arquitectura del sistema. El público objetivo son los desarrolladores actuales y futuros que trabajan en el proyecto. Necesito describir lo que debería ser, pero también necesito describir las desviaciones de alguna manera.

Entonces, ¿dónde debo describir estos problemas? Software de seguimiento de errores? ¿O debería describir las desviaciones de la implementación de la arquitectura en el documento que describe la arquitectura del sistema?

Si está documentando un diseño o arquitectura de un sistema que ya se ha creado, el documento debe describirlo como construido y no como está diseñado o como está previsto. Si hay rarezas o discrepancias en la arquitectura, entonces este documento debe mencionar esos problemas y explicarlos lo más posible a un lector.

Si puede obtener información de personas que han trabajado en el sistema desde el principio (o al menos más tiempo que usted), sería útil capturar más información sobre lo que realmente se pretendía y por qué la arquitectura y el diseño se desviaron de esto. intención.

Al final del día, un documento de diseño debe servir como guía para el código. Si el documento no ayuda a un nuevo desarrollador a comprender el estado actual de la base del código y cómo está estructurado, entonces el documento no es útil.

Este documento debe ser un documento vivo que se utilice para guiar la planificación futura y el diseño de cambios en el sistema y luego se actualice en consecuencia, dentro de su proceso de desarrollo. A medida que el diseño cambia y evoluciona con el tiempo, el documento también debería ayudar a los desarrolladores a comprender por qué las cosas son como son en la actualidad.

Si está buscando consejos para capturar la arquitectura, me gusta el enfoque recomendado en el Estándar IEEE 1016-2009 Estándar IEEE para Tecnología de la Información - Diseño de Sistemas - Descripción del Diseño de Software . Proporciona una estructura razonable para una descripción del diseño, que se puede utilizar para capturar información de diseño tanto a nivel arquitectónico como detallado.

También consideraría estas desviaciones como una forma de deuda técnica. Puede ser una gran empresa, quizás incluso un pequeño proyecto, solucionar los problemas, recomendaría hacer más visible la existencia de la deuda técnica. Si eso significa que usa su herramienta de seguimiento de defectos, puede colocar uno o más problemas allí. Si tiene otra herramienta que utiliza para rastrear sugerencias y mejoras del software, ese puede ser otro lugar para ponerlo.

Al formalizar la arquitectura del sistema, es importante que comprenda no solo el valor detrás de lo que la arquitectura aportará, sino también comprender y apreciar lo que debería ser.

Los objetivos principales del software o la arquitectura técnica es identificar los requisitos no funcionales que cumplen los atributos de calidad que impulsarán la arquitectura del sistema .

Sobre requisitos no funcionales:

Un requisito no funcional es un requisito que especifica criterios que pueden usarse para juzgar el funcionamiento de un sistema, en lugar de comportamientos específicos. Se contrastan con los requisitos funcionales que definen comportamientos o funciones específicos. El plan para implementar los requisitos funcionales se detalla en el diseño del sistema. El plan para implementar requisitos no funcionales se detalla en la arquitectura del sistema.

En términos generales, los requisitos funcionales definen lo que se supone que debe hacer un sistema y los requisitos no funcionales definen cómo se supone que debe ser un sistema. ... Los requisitos no funcionales a menudo se denominan "atributos de calidad" de un sistema. Otros términos para requisitos no funcionales son "cualidades", "objetivos de calidad", "requisitos de calidad de servicio", "restricciones" y "requisitos no conductuales"

Por supuesto, identificar los requisitos arquitectónicamente significativos tiene sentido cuando se trata de un proyecto totalmente nuevo, sin embargo, cuando se trabaja con el software existente, es mejor ser lo más disciplinado posible. No querrá que su arquitectura de software se vea influenciada por el sistema existente.

La arquitectura de software para ser autoritario realmente necesita ser 3 cosas.

Declarativo

Esta es la parte de la documentación en la que declaras NO LO QUE ES, sino cómo DEBEN SER las cosas. Hacemos esto mediante el uso de varias vistas arquitectónicas del sistema. Definimos los componentes que deberían ser, cómo interactúan y luego, opcionalmente, profundizamos en cada componente para obtener vistas más detalladas que declaran cómo debe diseñarse el sistema.

Esta es una distinción importante. El diseño del sistema debe estar limitado por la arquitectura del sistema, de hecho, son cosas separadas pero relacionadas.

Razón fundamental

El fundamento de su arquitectura de software es lo que proporciona legitimidad y autoridad a las decisiones de arquitectura que se tomaron. ¿Tal vez se tomó la decisión de utilizar un detector de eventos Pub / Sub a través de MQ para activar un trabajo por lotes y lo diagrama?

¿Por qué se tomó esta decisión? Explicamos por qué en la sección Justificación y vinculamos nuestra explicación a Requisitos no funcionales, Objetivos de atributos de calidad o Requisitos arquitectónicamente significativos. (Por ejemplo, los trabajos deben ser asíncronos y repetibles, la mantenibilidad como un atributo de calidad impulsa que, en caso de una falla del trabajo por lotes, los trabajos puedan reiniciarse a través de un mensaje MQ, el sistema debe tener pérdida de mensajes cero con comunicación asincrónica, etc. ..)

Riesgos

Ahora que ha declarado cómo debe ser la arquitectura y lo ha demostrado con su justificación, ahora puede identificar los riesgos en el estado actual del sistema en el que esto no se cumple.

(Por ejemplo, la validación del lado del servidor se está duplicando en el código Javascript del lado del cliente. Esto es una violación del principio DRY y esto va en contra del atributo de calidad de mantenimiento. No hay requisitos no funcionales definidos alrededor del rendimiento en esta área, por lo que no hay justificación para el comportamiento actual del sistema)

Sus riesgos también pueden diagramar dónde se está desviando actualmente el estado actual de la arquitectura. Estos riesgos pueden ser abordados por el equipo de desarrollo ahora, ya sea a través de su plan de proyecto o agregando esto a la cartera de pedidos.

Realmente necesita decidir si se supone que debe documentar la estructura actual del proyecto, o la estructura deseada del proyecto, o ambas.

Puede documentar el objetivo, con el fin de guiar el desarrollo futuro a lo largo de las líneas deseadas, y aumentar las desviaciones como errores (tal vez vincular a estos errores desde las partes relevantes del documento). O puede documentar la realidad para proporcionar una introducción / descripción general del código. O bien, puede documentar ambos en paralelo, de modo que simultáneamente tenga una guía para el desarrollo futuro y una descripción precisa del código actual en un solo lugar. Todos son razonables dependiendo de para qué se supone que es el documento, por lo que no creo que podamos decirte útilmente cuál hacer.

También debe tener en cuenta que la arquitectura deseada podría no estar universalmente acordada entre los involucrados (ya sea porque quieren cosas diferentes o porque algunos de ellos se han dado cuenta de que algunos deseos compartidos originales eran imposibles o poco prácticos y, por lo tanto, recurrieron a escribir el código existente que se desvía de la meta). Por lo tanto, también necesita saber si tiene autoridad para decidir qué es lo que desea, y si no quién lo hace. ¡La estructura existente al menos tiene la virtud de que solo hay una para documentar!

Escriba en el documento de diseño de arquitectura lo que se suponía que debía ser, y para cada conflicto encontrará un ticket en el rastreador de errores que describe el conflicto. La sección de comentarios del ticket ofrecerá una plataforma para que las personas relevantes discutan ese conflicto en particular.

Tenga en cuenta que la resolución de cada uno de estos tickets puede ser cambiar la implementación para que coincida con el diseño, pero también puede ser cambiar el diseño para que coincida con la implementación. Idealmente, se prefiere el primero, pero a veces hay restricciones técnicas y / o comerciales que hacen que sea más eficiente / pragmático / posible elegir el segundo. En ese caso, puede ser una buena idea consultar el ticket del documento de diseño de arquitectura, para que los futuros lectores que no entiendan por qué se eligió esa elección de diseño inferior en particular puedan leer la discusión en el ticket y comprender el razonamiento detrás eso.

Me inclinaría a escribir un documento arquitectónico organizado en 3 secciones principales.

La primera presentación del diseño / arquitectura que se pretendía inicialmente. Esto permitirá a los nuevos desarrolladores / lectores tener una idea de lo que se supone que debe hacer el sistema y obviamente debería estar vinculado a los requisitos / casos de uso, etc.

La segunda sección debería explicar muy claramente exactamente qué es realmente la arquitectura . Esto permite a los nuevos desarrolladores / lectores tener una idea del estado actual del juego y de lo que están tratando si miran el software (y potencialmente otra documentación). Esta sección debe indicar claramente la diferencia entre lo que se pretendía y la realidad, ya que esto probablemente resaltará cosas que están muy mal con la arquitectura original (¡con suerte no demasiadas!) Y áreas donde hay atajos / pirateos (probablemente algunos si hubiera se ha hecho un gran grado de presión sobre el equipo de desarrollo) y no se están cumpliendo los requisitos o el software está comenzando a verse "mal" diseñado, es decir, frágil, inestable, no portátil.

Finalmente, creo una sección que detalla las recomendaciones de lo que debe suceder ahora. Esto debería ser cualquier cambio en la arquitectura / diseño y una hoja de ruta para los cambios en el software en el presente con el fin de hacer realidad su visión.

Creo que esto cubre (a alto nivel) lo que hay que capturar. La forma en que hace esto en términos de las subsecciones del documento o el software de seguimiento de errores que emplea depende del dominio en el que está trabajando / preferencia personal / tamaño del equipo / presupuesto / escala de tiempo, etc.