Soy un desarrollador aficionado y todos mis programas hasta ahora eran lo suficientemente simples como para documentarse en el código. Mientras leía el código, estaba claro lo que estaba haciendo tal y tal acción (mi prueba estándar fue mirar el código 6 meses después y entender todo a la primera lectura, y tengo un corto espacio de memoria).
Ahora me enfrento a un programa que está superando mis capacidades para recordar las diversas interacciones entre
- el código en sí
- los índices en la base de datos
- las interacciones entre varios módulos (código central "trabajador" y "biblioteca")
Mi documentación actual es una pizarra donde tengo todo tipo de cuadros y flechas que apuntan al código, a los índices de la base de datos, a las acciones que se ejecutan, al cambio de estado, etc. Solo como referencia, un fragmento del desastre:
Mi pregunta es si existe un conjunto estándar o nombrado de mejores prácticas (nombrado en el sentido de que este es un conjunto de prácticas que se agruparon bajo un nombre específico) para la documentación de productos más complejos.
¿Cuáles son las palabras clave que debo buscar? (Los intentos generales de "documentar estándares de arquitectura de software" y variaciones similares generalmente condujeron a software para flujos de trabajo o sistemas CAD de arquitectura de edificios).
También espero que no haya mejores prácticas generales para descripciones de alto nivel y que cada uno construya su propia filosofía.
Respuestas:
No hay un estándar al que todos se adhieran. Los proyectos de software pueden variar mucho (piense: helloworld.py vs el código en el transbordador espacial).
Un método muy común es usar el modelo 4 + 1 . En lugar de tratar de agrupar todo en un solo estilo de documento, esta metodología divide el diseño en cinco componentes:
Las diversas vistas describen el producto desde cuatro perspectivas diferentes. Los escenarios son donde viven los casos de uso y describen la interacción de las otras vistas.
Nota: Este es un modelo conceptual y no está vinculado a ninguna herramienta específica.
Usted puede leer más aquí:
fuente
En mi humilde opinión, UML no es una herramienta que funcione bien para documentar la arquitectura de software del mundo real. Los diagramas de clases son útiles, pero utilizan un nivel de abstracción que a menudo es demasiado bajo para este propósito. Los diagramas de casos de uso suelen ser demasiado "de alto nivel" y pierden ciertos aspectos. Otros tipos de diagramas UML tienen problemas similares (para ser justos, los diagramas de paquetes, diagramas de implementación, diagramas de componentes pueden documentar ciertos aspectos arquitectónicos, pero personalmente nunca los encontré muy útiles).
Si está buscando una forma práctica y pragmática de documentar arquitecturas de alto nivel, le sugiero que se familiarice con los diagramas de flujo de datos . Estos son fáciles de entender y tienen la ventaja de que pueden escalar a diferentes niveles de abstracciones. Los he encontrado más útiles para documentar diferentes tipos de sistemas. Lástima que no hayan encontrado el camino hacia UML, pero de todos modos encontrarás muchas herramientas, incluso gratuitas, como Dia o DrawIO , para hacer estos diagramas.
Como nota al margen, ¿por qué necesita "índices en la base de datos" en una documentación de alto nivel? Creo que son un detalle de implementación de su modelo de datos (¿relacional?), Y si los agrega o no es, según mi experiencia, más una cuestión de rendimiento y optimización.
fuente
El lenguaje de modelado unificado (UML) es un lenguaje de modelado de desarrollo general en el campo de la ingeniería de software, que está destinado a proporcionar una forma estándar de visualizar el diseño de un sistema.
fuente
Creo que solíamos hacerlo mejor. UML parecía arrojar al bebé con agua del baño. Al proporcionar un lenguaje de modelado unificado, abolió la distinción entre arquitectura e implementación. O si no tenía la intención de que esto pareciera ser efectivo.
He visto algunos modelos UML monstruosos y, francamente, no hacen nada por mí que el código no pueda hacer, y lo hacen mejor.
fuente