Vamos adicionar um ARCHITECTURE.md

 (matklad.github.io)
26 pontos por xguru 2021-02-08 | 1 comentários | Compartilhar no WhatsApp

  • Um texto propondo adicionar ao repositório um arquivo que explique a arquitetura do projeto para facilitar a participação em projetos open source

  • A maior diferença entre quem contribui ocasionalmente para um projeto e os desenvolvedores centrais é o nível de compreensão da arquitetura do projeto

  • Se você não estiver familiarizado com a estrutura, escrever um patch pode levar mais do que o dobro do tempo, mas descobrir onde corrigir algo pode levar mais de 10 vezes mais tempo

  • Escrever um arquivo como ARCHITECTURE.md explicando a arquitetura em alto nível

→ Escreva de forma curta para que qualquer pessoa possa ler, organizando apenas as partes que não mudam com frequência

→ Não tente sincronizar com o código; em vez disso, revise de novo cerca de duas vezes por ano

Como escrever o conteúdo

  • Comece com uma visão panorâmica (bird's eye view) do problema que se está tentando resolver

  • Um mapa do código um pouco mais detalhado: “Onde está a parte que faz X?”

  • Explique aproximadamente os módulos e as relações entre eles: o que cada módulo faz deve ser ligado a outros documentos

  • Inclua os nomes de arquivos, módulos e tipos importantes

→ Isso permite que quem lê possa pesquisar pelos nomes; não use links diretos (eles podem quebrar)

  • Deixe claras as fronteiras entre camadas e sistemas
  • Bons exemplos

Leituras relacionadas

1 comentários

 
xguru 2021-02-08

E também é uma boa sugestão pedir, se possível, que o README.md principal inclua explicações sobre cada pasta do projeto.

Exemplo: https://github.com/diem/diem/…

Se possível, seria bom adicionar uma explicação em cada pasta, e seria ótimo se o GitHub exibisse esse conteúdo no nível superior quando houver um README na pasta.

Relacionado a isso, veja também os Architecture Decision Records.