Existe um padrão para documentar a arquitetura de alto nível de um programa?

Sou um desenvolvedor amador e todos os meus programas até agora eram simples o suficiente para serem documentados dentro do código. Ao ler o código, ficou claro o que eu estava fazendo tal e tal ação (meu teste padrão foi examinar o código seis meses depois e entender tudo na primeira leitura - e eu tenho pouco espaço de memória).

Agora estou diante de um programa que está superando minhas capacidades para lembrar as várias interações entre

• o próprio código
• os índices no banco de dados
• as interações entre vários módulos (código principal "worker" e "library")

Minha documentação atual é um quadro branco onde eu tenho todos os tipos de caixas e setas que apontam para código, índices de banco de dados, ações em execução, alteração de estado etc. Apenas para referência, um fragmento da bagunça:

Minha pergunta é se existe um conjunto padrão ou nomeado de práticas recomendadas (denominado no sentido de que este é um conjunto de práticas agrupadas sob um nome específico) para a documentação de produtos mais complexos.

Quais são as palavras-chave que devo procurar (tentativas gerais de "padrões de arquitetura de software de documentos" e variações semelhantes geralmente levam a software para fluxos de trabalho ou construção de sistemas CAD de arquitetura).

Também espero que não haja práticas recomendadas gerais para descrições de alto nível e que todos construam sua própria filosofia.

Não existe um padrão ao qual todos sigam. Os projetos de software podem variar bastante (pense: helloworld.py vs o código do ônibus espacial).

Um método muito comum é usar o modelo 4 + 1 . Em vez de tentar compactar tudo em um único estilo de documento, essa metodologia divide o design em cinco componentes:

• A visão Desenvolvimento
• A visão lógica
• A visão física
• A visualização Processo
• Cenários

As várias visualizações descrevem o produto de quatro perspectivas diferentes. Os cenários são onde os casos de uso residem e descrevem a interação das outras visualizações.

Nota: Este é um modelo conceitual e não está vinculado a nenhuma ferramenta específica.

Você pode ler mais aqui:

1. 4 + 1 modelo de vista arquitetônica (wikipedia)
2. Projetos arquitetônicos - O modelo de exibição “4 + 1” da arquitetura de software (documento IEEE - pdf)

O IMHO UML não é uma ferramenta que funciona bem para documentar a arquitetura de software do mundo real. Os diagramas de classes são úteis, mas use um nível de abstração que geralmente é muito baixo para esse fim. Os diagramas de casos de uso geralmente são "de alto nível" e perdem certos aspectos. Outros tipos de diagrama UML têm problemas semelhantes (para ser justo, diagramas de pacotes, diagramas de implantação, diagramas de componentes podem documentar certos aspectos da arquitetura, mas pessoalmente nunca os achei muito úteis).

Se você está procurando uma maneira prática e pragmática de documentar arquiteturas de alto nível, sugiro que você se familiarize com os diagramas de fluxo de dados . Eles são fáceis de entender e têm a vantagem de poderem ser dimensionados para diferentes níveis de abstração. Eu os achei mais úteis para documentar diferentes tipos de sistemas. Pena que eles não encontraram o caminho para a UML, mas, no entanto, você encontra muitas ferramentas - mesmo gratuitas, como Dia ou DrawIO - para fazer esses diagramas.

Como uma observação lateral, por que você precisa de "índices no banco de dados" em uma documentação de alto nível? Eu acho que eles são um detalhe de implementação do seu modelo de dados (relacional?) E se você os adiciona ou não, é - na minha experiência - mais uma questão de desempenho e otimização.

A UML (Unified Modeling Language) é uma linguagem de modelagem de desenvolvimento geral e de propósito geral no campo da engenharia de software, cujo objetivo é fornecer uma maneira padrão de visualizar o design de um sistema.

Eu acho que costumávamos fazer melhor. UML parecia jogar o bebê fora com água do banho. Ao fornecer uma linguagem de modelagem unificada, aboliu a distinção entre arquitetura e implementação. Ou se não pretendia isso, parecia ter efeito.

Eu já vi alguns modelos UML monstruosos e, francamente, eles não fazem nada por mim que o código não possa fazer, e faça melhor.