Com o passar do tempo e a evolução das tecnologias, construir software tornou-se mais rápido, porém mais complexo na mesma proporção. Por isso, ferramentas que organizam e principalmente documentam a tomada de decisão sobre arquitetura de software são mais do que bem-vindas. Neste artigo nós vamos te apresentar o que é Architecture Decision Records (ADR) e como adotamos esse documento na Zup.
Mas vamos dar um passo para trás e voltar a falar sobre agilidade e complexidade no desenvolvimento de software. Isso se deve, principalmente, a dois fatores: a mudança do papel do software e a natureza do software. A seguir vamos ver eles em detalhes.
A mudança do papel do software: software como meio para atingir um objetivo
Nos primórdios do desenvolvimento de aplicações, o software surgiu com o propósito único e exclusivo de processar dados. Nessa época, o hardware era um um ponto de maior atenção, principalmente, devido o seu custo e consequentemente isso tornava o uso dessa tecnologia pouco acessível.
Com a evolução econômica e tecnológica, o software deixou de só processar dados e começou a ter um papel estratégico; surgindo assim os sistemas de informações, onde esse processamento de dados passou a auxiliar em tarefas e tomadas de decisões nas empresas.
O hardware já não era um fator determinante e isso tornou a tecnologia mais acessível. Em paralelo, às mudanças tecnológicas e econômicas continuaram a acontecer e o software passou a ser utilizado de forma massiva e não mais um privilégio para poucas pessoas; se tornando um fator de inovação e vantagem competitiva para quem o utilizava.
Essa mudança de escopo e atuação transformou o impacto do software no negócio, e isso fez seu uso se tornar estratégico, e um meio para atingir o seu objetivo.
Essa nova visão mudou a forma de fazer software. Surgiram assim as metodologias ágeis, com o propósito de acelerar e facilitar as entregas e as mudanças durante o desenvolvimento de um software. A necessidade era que o desenvolvimento funcionasse rápido e de forma consistente, para que as mudanças não afetassem negativamente o negócio.
A natureza do software: inconstância e evolução
Alinhado a toda essa mudança de papel, podemos afirmar que um software possui três características: complexidade, efemeridade e mutabilidade.
Complexidade. O software não é somente código; envolve tecnologia, pessoas, processos e negócios.
Efemeridade – Tecnologias vêm e vão diariamente. Uma funcionalidade ou um software inteiro pode se tornar inviável/obsoleto de uma hora para outra, seja por uma tecnologia depreciada, uma vulnerabilidade mapeada, entre outros.
Mutabilidade – Devido às duas características citadas anteriormente, a mutabilidade se torna imprescindível para o software se manter funcionando. É preciso evoluir constantemente.
Afinal, o que é arquitetura?
Uma das discussões mais homéricas na área de engenharia de software, certamente é a definição do termo arquitetura. Resumindo sem polêmicas:
Arquitetura é a organização, comunicação e estrutura de todos os softwares e serviços de uma área, além de nutrir a visão tecnológica.
Modelo descentralizado para o sucesso!
Ao longo do tempo, diversas metodologias surgiram e substituíram outras. Esse é o caso, por exemplo, do Management 3.0 que condena o fordismo ou modelo top-down e valoriza um modelo com mais participação através de seis pontos:
- Energizar as pessoas
- Empoderar times
- Alinhar restrições
- Desenvolvimento de competências
- Crescer a estrutura
- Aprimoramento para melhorar sempre
A liderança precisa controlar o ambiente e não as pessoas. Isso quer dizer, fornecer todas as condições necessárias para que as atividades sejam realizadas da melhor maneira possível pelos indivíduos, e assim, maximizar os resultados.
Esse modo de liderança não faz sentido apenas para gestão de pessoas, mas para a arquitetura de software também. Afinal, como garantir que toda a estrutura funcione com apenas uma única pessoa controlando?
Naturalmente, não existe software ou uma única pessoa capaz de garantir uma boa governança. Afinal, não tem como fugir da Conway’s law. Em outras palavras, se a organização for confusa isso se refletirá no software. Logo uma arquitetura distribuída precisa considerar que o time seja bem distribuído e tenha autonomia.
Substituindo o “faça!”, por “faz sentido?”
Ao longo de anos, foi possível perceber as diversas tentativas de ter apenas uma pessoa como profissional de arquitetura ou um único setor responsável pela arquitetura. Mas, essas abordagens falharam miseravelmente, o que rendeu apenas boas piadas:
- “arquiteto ninja”: desaparece na mesma velocidade que apareceu.
- “time mestre dos magos”: possui o título, mas some nos momentos mais críticos.
Vale sempre salientar que o maior papel de profissionais de arquitetura, é escolher o trade-offs das decisões de arquitetura, ou seja, o contexto é a chave para qualquer decisão estratégica em nível tecnológico.
Outro ponto é o livro “Skin in the game”, que fala que nós temos mais receio de tomar uma má decisão quando essa também nos impacta. Sem falar que o software vive em constante evolução e adaptação, e aprendemos isso com Manifesto Ágil, ou seja, uma boa decisão hoje, pode não ser uma boa decisão amanhã.
A solução para isso, é uma eterna vigilância de todos os times como arquitetos de software. Ou seja, a responsabilidade da arquitetura não é de uma única pessoa externa, mas de todo o time, incluindo a sua manutenção. Erik Dörnenburg confirma e relata isso na sua apresentação: Arquitetura sem profissionais de arquitetura (em inglês).
É preciso seguir um modelo descentralizado para solucionar esse problema. E hoje, é possível observar uma alta adesão e com resultados positivos, por exemplo, no livro Software Engineering at Google existe um sessão para condenar o mito de um único gênio.
Se focarmos no outro extremo, certamente, teremos insucesso, afinal, se todo mundo pode tomar decisões, isso pode resultar em uma mistura de soluções com um alto grau de complexidade. Ruth Malan defende o papel de profissionais de arquitetura, porém, como facilitadores.
Documentação, descentralização e inspiração: A melhor combinação para a escalabilidade da sua arquitetura
Existem uma série de falácias e mitos na área de engenharia de software e tenho plena convicção de que o self-documenting code está nessa lista. Precisamos fazer um bom código, fluido e próximo da linguagem ubíqua, porém, isso não nos exime de documentar o nosso código.
Em outras palavras, é necessário realizar as boas práticas de clean code como nomes significativos, tamanho dos métodos, menor curva ciclomática, aplicar o Domain-Driven Design (DDD), dentre outras boas práticas. Isso é apenas uma parte do trabalho de escrever um bom código e não o todo.
Existem múltiplos exemplos de bons softwares que pregam a importância da documentação, por exemplo:
Grandes empresas de software como a Red Hat possuem guias de como documentar o seu software. Além disso, existem profissionais com essa qualificação: Technical Writers.
Hoje em dia, a boa documentação de software é tão crítica quanto realizar testes.
A documentação garante a escalabilidade para a sua arquitetura e deixa claro para todo mundo as decisões e seus respectivos fundamentos, sem o risco de se perder com o tempo ou com a saída de alguém do time. Para arquitetura isso vai além, não é apenas qualidade, mas define onde estamos, o que erramos e para onde queremos ir.
Andrew Harmel-Law em seu artigo sobre escalabilidade de arquitetura (em inglês), defende a uma forma de trabalhar a arquitetura a partir de quatro princípios:
- Fórum Consultivo de Arquitetura: Um local para realização das conversas para conselhos. Essa conversa pode ser um fórum ou uma reunião semanal.
- Architecture Decision Records (ADR) leves: Um local para armazenar as decisões de arquitetura.
- Princípios de origem da equipe: Uma inspiração para unificar os objetivos da arquitetura.
- Seu próprio Tech Radar (Radar Tecnológico): A sua pilha tecnológica e sensores indicando a temperatura da sua tecnologia.
O que é Architecture Decision Records (ADR)?
Um ponto pouco mencionado nesse contexto de arquitetura é o Architecture Decision Records (ADR). Ele é um documento que captura as decisões de arquitetura com contexto e, principalmente, as suas consequências.
Não existe um padrão para estabelecer esse tipo de decisão. Ele já está presente em linguagens como Java, com JEPs, e em especificações de software como Jakarta, além das arquiteturas mais “triviais”.
Independente do formato, uma boa ADR precisa atender os seguintes requisitos:
- Ser simples de escrever e manter. Afinal, se for difícil de criar/manter, a ADR tende a entrar em desuso ou se tornar obsoleto muito rápido.
- Consistir em uma decisão arquitetural sustentável: Evite o esforço repetitivo, seja estratégico, realístico e mensurável.
- Seja claro e objetivo com relação a seu objetivo.
Estrutura básica de um Architecture Decision Records e um exemplo
Sendo assim, um documento ADR, geralmente, deve conter os seguintes campos:
- Title: Algo declarativo informando o seu propósito.
- Dica: Comece de forma incremental, ou seja, 01 título, 02 título, etc.
- Separe por ano, algo que seja fácil de buscar e ordenar de forma cronológica.
- Date: O dia do documento.
- Status: O estado da ADR, isso pode variar de acordo com a organização, pense em: rascunho, revisado, aprovado ou reprovado.
- Context: A explicação do fato e do contexto de forma rica, simples e direta.
- Decision: A conclusão que foi realizada com base no contexto.
- Consequences: Com base no que entendemos de arquitetura, quais são os trade-offs dessa ação. É importante listar todas as consequências, afinal, decisões de arquitetura são baseadas em estudo e em análise e destacar um estudo prévio é muito importante.
Veja abaixo um exemplo simples da estrutura de um Architecture Decision Records:
1. Record architecture decisions
Date: 21.07.2017
Status
Aceito
Context
Todas as nossas decisões, estudos e planejamento de arquitetura serão documentados a partir de uma ADR
Decision
Será utilizado um modelo simples de ADR
Consequences
Todas as nossas decisões devem ser escritas, revisadas e traduzidas para garantir clareza, transparência e escalabilidade na nossa arquitetura.
Esse é apenas um exemplo, não é nada definitivo, é possível adicionar e remover campos de acordo a necessidade da sua organização.
Como fazemos no Open Source da Zup?
Descentralização e documentação são as chaves dos grandes cases de sucesso e também a recomendação das literaturas. De uma forma bem semelhante, também defendemos uma estrutura descentralizada e orientada a documentação no time Open Source da Zup.
Tentamos trabalhar com quatro frentes para garantir uma comunicação fluida com uma maior flexibilidade, isso de forma descentralizada e também compartilhada.
O foco na escalabilidade de arquitetura é garantir que não existe uma única pessoa ou algum ponto de falha. A documentação, certamente, é uma maneira de garantir isso.
- Tech Radar: Monitoramos as tecnologias que o time conhece, estuda e define níveis de utilização na organização.
- C4-model: Um mapa de toda a arquitetura, seus componentes e como elas se encaixam.
- Architecture Decision Records: Motivo já mencionado anteriormente.
- Comunicação ativa de ideais e sincronização: Pode ser síncrona ou assíncrona, sempre baseando no contexto e priorizando a forma assíncrona.
Como fazemos ADRs?
No time, existe uma forte filosofia de tratar todas as coisas como código, inclusive a documentação. Já temos experiência com isso e trabalhamos junto a equipe de Technical Writing dessa maneira.
Nós optamos pelo MADR como modelo padrão construção de Architecture Decision Records.
Além disso, adotamos o Log4Brains para gerenciamento e visualização das ADRS. Ele permite uma visualização com histórico e transforma os Markdowns escritos em HTMLs para exibição.
Conclusão
Assim como no mundo do software, uma arquitetura escalável garante que o maior número de profissionais de arquitetura realizem essa atividade sem quebrar ou mudar o foco. Além disso, permite que as decisões sejam tomadas de forma assertiva, evitando a mudança ou aceitação cega; algo recorrente em projetos com histórico e contexto não devidamente mapeados.
A garantia de que todo mundo está caminhando em uma única direção, certamente, é uma boa documentação.
Dentro do time Open Source da Zup, seguimos essa filosofia através da comunicação síncrona ou assíncrona, com recursos muito importantes como Tech Radar, C4-model e o Architecture Decision Records (ADR). E com essa transparência, atenção no código, testes e documentação acreditamos que a qualidade dos nossos projetos seguirá fluindo para o infinito e além.
Referências:
