O código diz o quê; ninguém diz porquê
Qualquer pessoa pode ler na configuração que a base de dados é relacional, que a fila é gerida ou que o serviço corre em contentores. O que não se consegue ler é porquê: que problema resolvia, que outras opções foram consideradas, o que se sacrificou ao escolher aquela.
Sem esse porquê, cada pessoa nova tem duas opções más: não mexer em nada por medo ou mudar tudo por desconhecimento.
O registo de decisão
Um registo de decisão de arquitetura (ADR, pela sigla em inglês, uma prática popularizada por Michael Nygard) é um documento curto, um por decisão, que se guarda junto ao código e nunca se apaga.
As suas partes:
- Título e estado. O que se decidiu e em que situação está: proposta, aceite, substituída por outra.
- Contexto. Que problema havia e que restrições existiam nesse momento. É o que mais se esquece e o que mais importa.
- Opções consideradas. Pelo menos duas, com as suas vantagens e desvantagens. Se só houve uma opção, não foi uma decisão.
- Decisão. O que se escolheu, em uma ou duas frases.
- Consequências. O que se ganha, o que se perde e o que obriga a fazer depois.
- Custo estimado. Quanto custa operar o que se escolheu. É a parte que quase ninguém escreve e a que mais se agradece depois.
Quando escrever um
Nem toda a escolha merece um registo. A regra prática: escreve-se quando a decisão é cara de reverter ou vai ser herdada por outra pessoa. Escolher o motor de base de dados, sim. Escolher o nome de uma variável, não.
Como evitar a burocracia
- Uma página, no máximo. Se não couber, são duas decisões.
- Escreve-se no momento, não depois. Dez minutos no dia da decisão.
- Não se edita: substitui-se. Se uma decisão muda, escreve-se uma nova que cita a anterior. Assim fica a história completa.
- Vive com o código, no mesmo repositório, para ser revisto e versionado da mesma forma.
Um conjunto de registos de decisão é a memória do sistema. É o que permite que alguém que chega daqui a um ano perceba numa tarde o que levou meses a decidir.
Como o aplicamos: Arquitetura Cloud.