Escreva documentos de decisão de arquitetura em projetos de software
Se você é desenvolvedor de software já deve ter sido responsável por trabalhar com código legado, escrito por outra pessoa, e ao entender o projeto você se pergunta: “Por que fizeram tão mal feito assim?” ou “Por que utilizaram essas tecnologias para um problema desse tipo?".
Muitas vezes as decisões tomadas em um projeto são consequências da cultura da empresa, do processo de desenvolvimento ou das restrições existentes no momento da tomada de decisão. Todos os profissionais, em algum momento, podem ter tomar uma decisão ou implementar algo que foi decidido mesmo sem concordar.
Por isso é extremamente importante documentar as decisões tomadas em projetos de software para compartilhar o entendimento delas antes de qualquer alteração no projeto.
Introdução
O Documento de Decisão de Arquitetura ou Architecture Decision Record (ADR) deve ser um arquivo de texto simples descrevendo os motivos que levaram à determinada decisão e suas consequências. Existem vários templates disponíveis e você pode armazenar esses documentos em qualque lugar. Eu gosto de armazenar esses arquivos no repositório Git do projeto para serem versionados. Eu crio um arquivo Markdown para cada decisão tomada e armazeno dentro da pasta docs/adr do projeto ou crio um repositório específico para isso quando um projeto é composto por vários repositórios.
Imagine o cenário onde uma aplicação web registra os logs no banco de dados. Existem diversas técnicas mais elegantes para gerenciamento de logs e talvez essa seja uma das menos indicadas. Agora leia a ADR abaixo e reflita sobre seu pensamento nesse momento:
SALVAR LOGS NO BANCO DE DADOS
Toda requisição para a API Rest gera um log contendo dados do request, informações processadas e erros.
- Status: Aceito
- Context: Não temos agilidade para visualizar os logs em produção. A plataforma atual de logs da empresa é muito lenta, ruim de visualizar as mensagens e não permite buscas por termos. A empresa está implantando um novo sistema para gerenciamento de logs mas vai levar algum tempo ainda para entrar em funcionamento.
- Decision: Ao testar as integrações com outros sistemas, é inevitável os erros em produção. As documentações deles estão desatualizadas e quando o software vai para produção, nos deparamos com parâmetros diferentes do que foi documento e precisamos analisar os logs para entender. Atualmente a plataforma de logs é lenta e precisamos conectar via VPN. Criamos um esquema de log que salva no banco de dados da aplicação e para não perder performance, o registro do log é assíncrono utilizando o Celery, que é o agendador mais utilizado em projetos em Python como o nosso.
- Consequences: Isso traz agilidade para visualizar os logs em tempo real porém não é a melhor solução. Sugerimos uma stack mais adequado ao gerente do processo de mudanças e solicitamos um monitoramento da aplicação pois se ela tiver muitas requisições pode levar à problemas de performance.
Um documento de decisão de arquitetura nos ajuda a não fazer um julgamento precipitado sobre o que foi feito.
Existem diversos templates, porém, não se prenda restritamente à um deles. Crie um documento no formato que faça sentido no contexto do projeto e que seja de fácil entendimento para todos.