Vamos entender neste artigo o que são os ADR´s ou architecture decision records ou em pt-br registros de decisão de arquitetura.
Quando você entra em um projeto provavelmente algumas perguntas virão a sua cabeça e uma delas provalvelmente é o porquê uma determinada solução tecnológica foi aplicada. E não será dificil voce obter como resposta “ninguém sabe explicar o motivo“.
Quando não temos um contexto nossa primeira reação vai ser pensar em mudanças e talvez até implementá-las sem saber o real motivo que levou a equipe a usar uma tecnologia x ou y, isso pode acarretar em custo de tempo e dinheiro, duas coisas que não podemo nunca perder na vida certo?
A falta de documentação clara e organizada das decisões de arquitetura em um projeto de software ou sistema é o principal problema que os Architecture Decision Records (ADRs) resolvem. Quando as decisões arquiteturais são tomadas, pode ser difícil lembrar por que uma escolha foi feita e quais alternativas foram consideradas. Além disso, as decisões podem ser tomadas por diferentes membros da equipe em momentos diferentes, o que pode levar a inconsistências e falta de clareza.
ADRs fornecem uma estrutura para documentar e organizar as decisões arquiteturais de um sistema, neste documento são fornecidos justificativas, limitações e consequências para que a decisão seja tomada de forma clara e concisa, permitindo que todos envolvidos entendam o pensamento por trá da escolha.
Há várias razões pelas quais os Architecture Decision Records (ADRs) são úteis e valiosos para o desenvolvimento de software. Algumas dessas razões incluem:
- Clareza e transparência: Ao registrar as decisões arquiteturais em ADRs, as justificativas, limitações e consequências podem ser compartilhadas com todos os membros da equipe de desenvolvimento. Isso ajuda a garantir que todos tenham uma compreensão clara do sistema como um todo, além de promover a transparência e a comunicação aberta entre a equipe;
- Evitar a repetição de erros: Documentar as decisões arquiteturais em ADRs pode ajudar a evitar que erros do passado sejam repetidos. Se a equipe tiver acesso a informações claras sobre o raciocínio por trás de uma decisão anterior, eles poderão avaliar se a mesma escolha é apropriada para a situação atual ou se outra alternativa deve ser considerada;
- Conformidade e auditoria: A documentação clara das decisões arquiteturais pode ser útil para fins de conformidade e auditoria. Os ADRs podem ajudar a demonstrar que a equipe tomou decisões informadas e cuidadosas em relação à arquitetura do sistema;
- Facilitar a colaboração: Ao compartilhar informações claras sobre as decisões arquiteturais em ADRs, a equipe pode colaborar de forma mais eficaz. Isso pode incluir a discussão de alternativas, a avaliação de riscos e a resolução de conflitos;
- Compreensão do sistema: A criação de ADRs pode ajudar a equipe a desenvolver uma compreensão mais profunda do sistema como um todo, incluindo como as diferentes partes se encaixam e interagem. Isso pode ser particularmente útil para novos membros da equipe que precisam se familiarizar com o sistema.
Ok! entendemos o que são as ADRs e sua utilidade. Mas como criar os documentos? podemos encontrar na internet varias ferramentas, você poderia até mesmo criar seus ADRs em documentos do word mas vou mostrar uma forma que gostei bastante depois de procurar várias alternativas.
Utilizando a forma abaixo você poderá manter um repositório git com seus documentos e aproveitar essa tecnologia para guardar as versões do seu documento.
Vamos utilizar o Visual Studio Code pra escrever nossos ADRs, para isso baixe a extensão ADR Manager no menu extensões:
Para facilitar o entendimento deixei uma estrutura de pastas e arquivos de exemplo no meu github, caso queira utilizar basta baixar ou fazer o clone para sua máquina.
Depois de baixar o projeto abra a pasta no Visual Studio Code:
Temos no projeto duas pastas:
- docs – pasta principal onde estão os ADRs, neste caso só temos um exemplo;
- another-docs – uma pasta secundária onde podemos colocar outros ADRs, ae fica ao seu critério essa separação
- na pasta .vscode temos as configurações em um arquivo .json neste momento somente com a pasta principal dos ADRs deste projeto.
Para visualizar os ADRs simplesmente em cima da pasta “docs” clique com o botão direito do mouse e escolha “Open ADR Manager”:
Irá abrir a lista de ADRs já cadastrados (no nosso exemplo só temos um):
Funcionamento muito simples, clique em “View” para editar o ADR, “Delete” para excluir e em “Add ADR” para gerar um novo.
Para simplesmente visualizar um ADR clique com o botão direito no documento e vá na opçao “Open Preview” :
Para criar um novo clique em “Add ADR“:
O entendimento desse formulário é relativamente tranquilo:
- Title – Crie um padrão composto por codigo e um texto curto que explique diretamente o tema Exemplo: 0001-use-java-as-programming-language.md;
- Last Updated – Data da última atualização;
- Status – Combo de escolhas (Proposed, Accepted,Rejected,Superseded) defina o status do ADR;
- Deciders – Coloque as pessoas envolvidas na construção do documento (separado por “,”);
- Tecnical Story – História técnica que está levando a construção do documento,
- Context and Problem Statement – Aqui deve ser escrito os fatos que levaram a tomada de decisão, colocar todas as informaçõe sobre o problema a ser resolvido, os objetivos do projeto, restriçoes e requisitos;
- Decision Drivers – Descreva “direcionadores” para a decisão final da arquitetura, vantagens e desvantagem para facilitar a decisão final;
- Considered Options – Elencar tecnologias similares para escolha, bem como vantagens e desvantagens de cada uma;
- Decision Outcome – Aqui vai a tecnologia escolhida no final do processo.
- Links – adicione referencias a outros ADR´s.
Em resumo, os ADRs resolvem o problema da falta de documentação clara e organizada das decisões de arquitetura em um projeto de software, promovendo a transparência, a clareza e a consistência nas decisões tomadas pela equipe.
Os ADRs resolvem esse problema, fornecendo uma estrutura para documentar e organizar as decisões de arquitetura. Eles ajudam a garantir que as justificativas, limitações e consequências de uma decisão sejam registradas de forma clara e concisa, permitindo que todos os membros da equipe entendam o raciocínio por trás da escolha.
E outro ponto muito importante, a decisão é de um time não de uma pessoa só, ou seja são várias pessoas pensando em um mesmo problema e chegando a uma solução única. Qual a probabilidade de acontecer um erro na escolha? bem eu considero que é bem menor do que somente um profissional escolhendo o caminho da arquitetura de um projeto.
Fico por aqui! se curtiu ou gostou do artigo comenta ae, qualquer comentário seja bom ou de criticas é bem vindo no sentido de melhorar!
Até mais!