Especificação técnica de "Architecture.md (2021)"

Recomendação para escrever ARCHITECTURE.md

• Recomenda-se fortemente que mantenedores de projetos open source adicionem um documento ARCHITECTURE ao lado de README e CONTRIBUTING.
• Este documento descreve a arquitetura de alto nível do projeto e, como deve ser lido por contribuidores recorrentes, é melhor mantê-lo curto.
• O documento ARCHITECTURE deve incluir apenas conteúdos que não mudam com frequência e, em vez de tentar sincronizá-lo com o código, o ideal é revisá-lo algumas vezes por ano.

Objetivo e importância do documento

• O conhecimento sobre a arquitetura física de um projeto é a maior diferença entre contribuidores em geral e desenvolvedores centrais.
• Se você não estiver familiarizado com o projeto, leva 2 vezes mais tempo para escrever um patch e 10 vezes mais tempo para descobrir onde o código precisa ser alterado.
• O arquivo ARCHITECTURE é uma forma eficaz de reduzir essa lacuna e também oferece uma oportunidade de refletir sobre a estrutura do projeto.

Estrutura do documento

• Ele deve começar com uma visão geral sob uma nova perspectiva do problema e fornecer um mapa de código detalhado que explique a relação entre os módulos.
• Arquivos, módulos e tipos importantes devem ser citados, mas, em vez de linkar diretamente, deve-se incentivar a busca pelos nomes para evitar necessidade de manutenção.
• Também é preciso apontar explicitamente as invariantes arquiteturais e destacar os limites entre as camadas.

Invariantes arquiteturais e limites

• Invariantes importantes muitas vezes são expressas pela ausência de algo, e é difícil percebê-las apenas lendo o código.
• Os limites entre camadas ou sistemas incluem implicitamente informações sobre a implementação do sistema e restringem todas as implementações possíveis.

Interesses transversais

• Após concluir o mapa de código, deve-se adicionar uma seção separada sobre interesses transversais.
• Um bom exemplo de documento ARCHITECTURE é o architecture.md do rust-analyzer.

Opinião do GN⁺:

• O documento ARCHITECTURE ajuda a entender o projeto e tem um papel importante para que novos contribuidores se familiarizem rapidamente com a base de código.
• Este documento esclarece a estrutura do projeto e destaca princípios e limites arquiteturais importantes, ajudando os desenvolvedores a compreender melhor o sistema.
• A adoção do documento ARCHITECTURE na comunidade open source pode contribuir para o crescimento sustentável e a manutenção do projeto, sendo uma abordagem muito útil e interessante para desenvolvedores.

[GN⁺]

Comentários do Hacker News

• Se você mantém um projeto open source e ele tem entre 10k e 200k linhas de código, recomendo fortemente adicionar um documento ARCHITECTURE.

  • A ideia é boa, mas acho que dá para incluir a arquitetura no Readme independentemente do tamanho do repositório. Por exemplo, coloco intencionalmente um diagrama de sequência em Mermaid no Readme principal para que todos os usuários possam entender o fluxo de trabalho.

• Essa abordagem é excelente como um modelo de baixa manutenção para projetos open source com muitos contribuidores ad hoc. Para projetos com engenheiros dedicados, vale considerar ADRs. Isso exige mais manutenção, mas é muito útil em reconstruções, pois registra o "porquê" e as "alternativas consideradas".

• Alguns anos atrás experimentei algo parecido em um dos meus grandes projetos paralelos:

  • Havia uma árvore de links para outros arquivos ARCHITECTURE.md no topo de cada arquivo.

• Todas as IDEs mostram a estrutura de pastas do projeto à esquerda com uma árvore de diretórios padrão. Existe alguma IDE que permita explorar o projeto com um grafo de dependências?

• É preciso ter cuidado ao generalizar o que o autor escreveu aqui para projetos de software em geral. Em grandes projetos open source com muitos contribuidores e pouco contexto, vale a pena manter esse tipo de documento. Mas, em projetos pequenos de trabalho, toda documentação escrita por desenvolvedores que já vi acaba ficando sem manutenção.

• Quanto mais curto for o documento, menor a chance de ele ser invalidado por mudanças futuras. Essa é a principal regra de um documento ARCHITECTURE — documente apenas as coisas com menor probabilidade de mudar com frequência. Não tente mantê-lo sincronizado com o código.

  • Interfaces têm menos probabilidade de mudar e [são mais difíceis!] (Parnas, sobre os critérios usados para decompor sistemas em módulos).

• Em todos os projetos, durante o onboarding mostramos um diagrama de arquitetura e uma breve descrição dos seus componentes.

  • Agora me surpreende como isso é raro em open source.

• Esta é uma prática muito útil. Muitos projetos têm alguns arquivos centrais (ou pacotes/módulos/etc.) onde a maior parte das mudanças acontece. Se você permitir que novos contribuidores (ou contribuidores que estão voltando depois de muito tempo) aprendam isso rapidamente, pode reduzir bastante o tempo necessário para começar a contribuir no projeto.

• Sempre fui fã desses pequenos padrões de documentação/diagramas em código:

  • desenvolvimento guiado por README
  • ARCHITECTURE.md
  • ADRs
  • arc42
  • C4
  • etc.
  • Agora coloco um vault do Obsidian dentro da pasta /docs do repositório git.
  • Em vez de usar o padrão de outra pessoa, organizo e refatoro a documentação como faço com minhas notas pessoais no Obsidian.
  • Tentei usar um subconjunto comum de Markdown que funcionasse tanto no GitHub (GFM) quanto no Obsidian, mas no fim desisti e passei a usar o markdown do Obsidian e seus recursos específicos.
  • O Obsidian tem Mermaid e LaTeX embutidos, além de um plugin para PlantUML.
  • Para imagens/diagramas visuais, há Canvas, DrawIO e Excalidraw embutidos.

• Discutido na época:

  • Architecture.md - fev. de 2021 (153 comentários)