Especificación técnica de "Architecture.md (2021)"

Recomendación para escribir ARCHITECTURE.md

• Se recomienda enfáticamente a los mantenedores de proyectos de código abierto agregar un documento ARCHITECTURE junto a README y CONTRIBUTING.
• Este documento explica la arquitectura de alto nivel del proyecto y, como debe ser leído por colaboradores recurrentes, conviene mantenerlo corto.
• El documento ARCHITECTURE solo debe incluir contenido que no cambie con frecuencia y, en lugar de intentar sincronizarlo con el código, es preferible revisarlo unas cuantas veces al año.

Propósito e importancia del documento

• El conocimiento de la arquitectura física del proyecto es la mayor diferencia entre un colaborador común y un desarrollador principal.
• Si no se está familiarizado con el proyecto, escribir un parche toma el doble de tiempo, y averiguar en qué parte del código hay que hacer cambios toma diez veces más tiempo.
• El archivo ARCHITECTURE es una forma efectiva de cerrar esa brecha y también ofrece una oportunidad para reflexionar sobre la estructura del proyecto.

Estructura del documento

• Debe comenzar con una visión general desde una nueva perspectiva del problema y proporcionar un mapa de código detallado que explique la relación entre los módulos.
• Debe mencionar archivos, módulos y tipos importantes, pero en lugar de enlazarlos directamente, conviene animar a buscarlos por nombre para que no requieran mantenimiento.
• Debe señalar explícitamente las invariantes arquitectónicas e indicar los límites entre capas.

Invariantes y límites arquitectónicos

• Las invariantes importantes a menudo se expresan como la ausencia de algo, y es difícil detectarlas solo leyendo el código.
• Los límites entre capas o sistemas contienen implícitamente información sobre la implementación del sistema y restringen todas las implementaciones posibles.

Aspectos transversales

• Después de completar el mapa de código, se debe agregar una sección separada sobre aspectos transversales.
• Un buen ejemplo de documento ARCHITECTURE es architecture.md de rust-analyzer.

Opinión de GN⁺:

• El documento ARCHITECTURE cumple un papel importante para ayudar a entender el proyecto y para que los nuevos colaboradores se familiaricen rápidamente con la base de código.
• Este documento aclara la estructura del proyecto y resalta principios y límites arquitectónicos importantes para ayudar a los desarrolladores a comprender mejor el sistema.
• La adopción del documento ARCHITECTURE en la comunidad de código abierto puede contribuir al crecimiento sostenible y al mantenimiento del proyecto, y es un enfoque muy útil e interesante para los desarrolladores.

[GN⁺]

Comentarios en Hacker News

• Si gestionas un proyecto open source y tiene entre 10k y 200k líneas de código, recomiendo fuertemente agregar un documento ARCHITECTURE.

  • La idea es buena, pero creo que se puede incluir la arquitectura en el Readme sin importar el tamaño del repositorio. Por ejemplo, coloco intencionalmente un diagrama de secuencia de Mermaid en el Readme principal para que cualquier usuario pueda entender el flujo de trabajo.

• Este enfoque es excelente como modelo de bajo mantenimiento para proyectos open source con muchos contribuidores ad hoc. En proyectos con ingenieros dedicados, habría que considerar ADRs. Requieren más mantenimiento, pero son muy útiles al reconstruir porque registran el "por qué" y las "alternativas consideradas".

• Hace algunos años experimenté con algo parecido en uno de mis grandes proyectos secundarios:

  • En la parte superior de cada archivo había un árbol de enlaces hacia otros archivos ARCHITECTURE.md.

• Todos los IDE muestran a la izquierda la estructura de carpetas del proyecto como un árbol de directorios estándar. ¿Existe algún IDE que permita explorar un proyecto mediante un grafo de dependencias?

• Hay que tener cuidado al generalizar a proyectos de software comunes lo que el autor escribió aquí. En proyectos open source grandes con muchos contribuidores y poco contexto, mantener este tipo de documentos sí vale la pena. Pero en proyectos pequeños de trabajo, todos los documentos escritos por desarrolladores que he visto terminan quedando sin mantenimiento.

• Mientras más corto sea un documento, menos probable es que quede invalidado por cambios futuros. Esta es la regla principal de un documento ARCHITECTURE: especifica solo las cosas que es poco probable que cambien con frecuencia. No intentes mantenerlo sincronizado con el código.

  • Las interfaces tienen menos probabilidad de cambiar y [¡son más difíciles!] (Parnas, Criteria To Be Used in Decomposing Systems into Modules).

• En todos los proyectos, durante el onboarding muestro un diagrama de arquitectura y una breve descripción de sus componentes.

  • Ahora me sorprende lo raro que es esto en open source.

• Esta es una práctica muy útil. Muchos proyectos tienen unos cuantos archivos clave (o paquetes/módulos/etc.) donde ocurre la mayoría de los cambios. Si ayudas a que los nuevos contribuidores (o los que vuelven después de mucho tiempo) se familiaricen rápido con ellos, puedes reducir muchísimo el tiempo necesario para empezar a contribuir.

• Siempre he sido fan de estos pequeños estándares de documentación/diagramas como código:

  • README-driven development
  • ARCHITECTURE.md
  • ADRs
  • arc42
  • C4
  • etc.
  • Ahora pongo un vault de Obsidian dentro de la carpeta /docs del repositorio git.
  • En lugar de usar el estándar de otra persona, organizo y refactorizo la documentación como si estuviera gestionando mis notas personales en Obsidian.
  • Intenté usar un subconjunto común de Markdown que funcionara tanto en GitHub (GFM) como en Obsidian, pero al final me rendí y usé el Markdown de Obsidian y sus funciones específicas.
  • Obsidian tiene Mermaid y LaTeX integrados, y hay un plugin para PlantUML.
  • Para imágenes/diagramas visuales, vienen integrados Canvas, DrawIO y Excalidraw.

• Se discutió en su momento:

  • Architecture.md - Feb 2021 (153 comentarios)