Todos que atuam com tecnologia já se deparam com situações em que ninguém sabe explicar o porquê de determinada soluções tecnológicas, é tipo a tartaruga em cima da árvore, todos sabemos que é impossível a tartaruga ter chego lá sozinha, logo alguém a colocou lá, entretanto como não temos o contexto, não fazemos ideia do porque a tartaruga está lá e para piorar, que efeitos positivos ou negativos podem ocorrer caso a tartaruga seja removida.
Pegando o gancho dessa analogia, podemos transportar essa mesma ironia para arquitetura de softwares, muitas vezes nos deparamos com soluções implementadas de formas anormais as práticas comuns e a nossa primeira reação é corrigi-la. Porém, precisamos contextualizar que se algo foi feito daquela maneira, com certeza existia um contexto a época que culminou nesta escolha, logo, é sempre muito simples entender as razões e consequências, se pudermos facilmente acessar essas informações, para elucidar as principais dúvidas da tomada de decisão no passado.
Para isso, Michael Nygard recomendou que fosse criado um documento chamado Architectural Decision Records (ADR), em tradução livre, Registro de Decisão de Arquitetura, seu propósito principal é capturar as tomadas de decisões arquiteturais, incluindo o contexto que em foi gerada, as consequências adotadas pela decisão. Esses simples documentos, promovem inúmeros benefícios, principalmente no contexto ágil, sendo alguns desses:
Integração de Novos Membros
Haverá todo um histórico de decisões que deve ser absorvido e que auxiliará na contextualização dos porquê somos e estamos assim. Desde uma simples decisão da adoção de uma tecnologia específica, como a linguagem para desenvolvimento de sites, até a utilização de micro serviços em containers.
Transferência de Conhecimento
Muitas vezes, sistemas são transferidos entre colaboradores, equipes, consultorias, ou seja, mover a propriedade dos sistemas para outra parte que assumirá o comando. Estando os contextos das decisões documentadas, nenhum conhecimento irá se perder no processo, porque os novos proprietários podem rapidamente entender como e por que a arquitetura do sistema evoluiu da maneira que evoluiu simplesmente lendo.
Alinhamento
Todos sabendo da presença desses documentos, será criado o hábito do conhecimento compartilhado das decisões, facilitando a consulta em níveis hierárquicos da arquitetura, de quais são os “combinados” dentro da corporação.
E como fazer acontecer? Simples, escrevendo os documentos de Registro de Decisão de Arquitetura no momento em que decisões de impacto significativo são feitas, ou nos mapeamento de débito técnico ou ainda nas implementações fora do comum.
Mas quando deve ser feito? Um documento pode ser escrito previamente ou posterior a solução, a preferência é que seja feito previamente para estimular a discussão das consequências, fomentando assim mais insumos para uma decisão assertiva. Nos casos posteriores, é necessário para criação de uma base histórica dos contextos que foram aplicados perpetuando o conhecimento.
E o processo como é? Os documentos de Registro de Decisão de Arquitetura são baseado num template com simples marcações em seções, composto pelo seguintes blocos:
Título
Composto por um código e um texto curto e direto sobre o tema. O código é para facilitar o controle e também a inter-relação entre os documentos.
Exemplo: ADR-0012 - Requisições API devem gerar logs
Data
A data que o documento foi criado.
Exemplo: 2021-mai-05
Status
Existem por padrão seis possíveis status, porém você tem a liberdade de criar seus próprios, segue os sugeridos:
Proposto: Criação do Documento.
Aceito: Decisão Aprovada.
Depreciado: Decisão não faz mais sentido.
Substituído: A decisão foi substituída - importante referenciar a que substituiu
Complemento: Uma decisão complementar - importante referenciar a original
Rejeitado: A decisão proposta foi rejeitada
Contexto do Problema
Neste bloco deve ser descrito os fatos que levaram a tomada da decisão, elencando todas as influências que estavam atuando no momento, sejam elas políticas, corporativas, econômicas, tecnológicas, ou mesmo sociais.
Exemplo: Não conseguimos visualizar os logs em tempo real das requisições, o que resulta em atraso do monitoramento preventivo de erros e comportamentos fora do comum das chamadas. Existe a possibilidade de aquisição de uma ferramenta para efetuar esse monitoramento, entretanto o processo é burocrático e lento. Sendo previsto a sua disponibilização em 6 meses.
Decisão
Neste bloco será descrita a decisão tomada, é vital relacionar com o problema descrito, utilizando a voz ativa com sentenças completas e organizadas em parágrafos.
Exemplo: Todas as requisições terão implementado em seu cabeçalho a chamada do sistema de log que salvará os dados em um banco de dados. As requisições ao sistema log são assíncronas. Utilizaremos o framework Log4Net para implementação.
Consequências
Este bloco talvez seja o mais importante, porque é aqui que deve ser descrito os resultados positivos e/ou negativos e/ou neutros da decisão, é neste ponto que deve fazer sentido a decisão tomada. Tudo que puder afetar o projeto deve ser registrado e também os débitos técnicos, ou seja, o que precisa ficar no radar para ser decidido no futuro.
Exemplo: O armazenamento “manual” dos logs em tempo real não é a melhor solução, principalmente com a necessidade de atualização de todas estruturas atuais de API que precisavam ser entregues em produção. É importante a implementação de um sistema de gerenciamento de APIs para que seja feito o monitoramento completo do ciclo de vida de uma requisição.
Esses documentos devem preferencialmente serem armazenados em repositórios acessíveis para todos, incentivando assim o compartilhamento de conteúdo e facilitando o acesso às decisões. É crucial que exista um nível organizacional hierárquico para demonstrar as decisões que são dependentes em camadas, por exemplo, uma decisão de arquitetura afeta automaticamente um departamento, que por consequência afeta um projeto.
Com a metodologia ágil cada vez mais presente nas empresas, estamos muito mais propensos às mudanças constantes, e para dar maior visibilidade às decisões tomadas, o documento de Registro de Decisão de Arquitetura nos ajuda a não fazer um julgamento precipitado sobre o que foi feito há época, oferecendo contexto para maior segurança aos times no entendimento do passado e fornecedor informações para melhor decisões no presente que afetam o futuro.
Marcelo Goberto de Azevedo
Arquiteto na GFT Brasil