Se o propósito das práticas de arquitetura de software é aumentar as chances de que os objetivos do negócio sejam atingidos – respeitando restrições e atributos de qualidade – é importante disseminar esses parâmetros, com o mínimo de ambiguidade e subjetividade, durante todo o ciclo de vida do software que, aliás, pode durar décadas começando muito antes da primeira linha de código ser escrita.
Documentação arquitetural em processos ágeis
Estamos descobrindo maneiras melhores de desenvolver software, fazendo-o nós mesmos e ajudando outros a fazerem o mesmo. Através deste trabalho, passamos a valorizar: 1) Indivíduos e interações mais que processos e ferramentas; 2) Software em funcionamento mais que documentação abrangente; 3) Colaboração com o cliente mais que negociação de contratos e 4) Responder a mudanças mais que seguir um plano. (Manifesto ágil)
Os processos ágeis de desenvolvimento de software são uma reação a métodos pesados que eram comuns no passado (com resquícios fortes dentro de muitas empresas ainda hoje, infelizmente).
Na ânsia de eliminar etapas desnecessárias para o desenvolvimento de sistemas de software, muitos “agilistas” resistem não apenas a documentação arquitetural mas a tudo que esteja relacionado com técnicas para a prática da arquitetura. Importante, entretanto, destacar que essa posição não é universal. Muitos expoentes das práticas ágeis – incluindo Martin Fowler, Robert Martin, Scott Ambler – reconhecem que essa conduta é perigosa.
Os métodos ágeis não se opõem à documentação, apenas à documentação sem valor. Documentos que auxiliam a própria equipe podem ter valor, mas somente se forem mantidos atualizados. Documentos grandes nunca são atualizados. Documentos pequenos e modulares têm pelo menos uma chance de serem atualizados. (Nygard)
Documentação arquitetural e a comunicação
Se a organização tem uma expectativa de que “todos devem ver todas as mensagens do chat” ou “todos precisam comparecer às massivas reuniões standup” ou “todos precisam estar presentes nas reuniões” para aprovar as decisões, então temos um problema de design da organização. A lei de Conway sugere que este tipo de comunicação muitos-para-muitos tende a produzir sistemas monolíticos, emaranhados, altamente acoplados e interdependentes que não suportam fluxo rápido. Mais comunicação não é necessariamente uma coisa boa. (Skelton e Pais)
Os componentes de um software, evidentes em sua arquitetura, interagem e são desenvolvidos por times que também precisam interagir. Ambos, componentes e times, precisam de interfaces qualificadas, sem revelar seus funcionamentos internos, para que comunicação eficiente aconteça.
Arquitetura de software é a divisão prudente de um todo em partes, com relações específicas entre essas partes. Esse particionamento é o que permite que grupos de pessoas – geralmente separados por limites organizacionais, geográficos e até mesmo de fusos horários – trabalhem em conjunto de forma cooperativa e produtiva para resolver um problema muito maior do que qualquer um deles resolve individualmente. (Clements et al.)
Arquitetura de software é o conjunto de decisões de design que, se feitas incorretamente, talvez causem o cancelamento do seu projeto. (Rosanski e Woods)
Fazer negócios sem anunciar [ou projetar uma arquitetura sem documentá-la] é como piscar para uma garota no escuro. Você sabe o que está fazendo, mas ninguém mais sabe. (frase adaptada de Steaurt Henderson Britt em Skelton e Pais)
(Documentação da) arquitetura de software e a complexidade
Há pelo menos três contribuições notáveis da arquitetura de software para o combate da complexidade:
- Divisão do problema – estruturando software em componentes que possam ser mantidos por times pequenos e que, depois, podem ser combinados, formando um sistema maior, a arquitetura autoriza, pelo menos por um tempo, a desenvolver partes de um software sem conhecer detalhes sobre como as outras funcionam. A ênfase passa ser nas interações.
- Aproveitamento do conhecimento dos times – facilitando, a partir de componentes pequenos e desacoplados, o reaproveitamento do conhecimento dos desenvolvedores na implementação do projeto (ex: alguém que já implementou um mecanismo de cobrança, terá uma boa ideia de como implementar essa solução). Também crescem as chances de encontrar boas fontes de conhecimento em livros, palestras, descrição de padrões, projetos de código aberto e mais.
- Adoção de abstrações – facilitando, ao ignorar detalhes menos significativos, os esforços para desenvolver soluções.
Em software, coisas maiores geralmente são feitas de coisas menores. Você sempre pode raciocinar sobre as coisas menores em um sistema (como linhas individuais de código), mas normalmente você achará mais eficiente pensar em coisas maiores (como clientes e servidores) [..] Você pode começar seu processo de raciocínio considerando o pequenos pedaços, como objetos e chamadas de procedimento, mas que seriam ineficientes e provavelmente o inundariam com detalhes. (Fairbanks)
Atividades suportadas pela documentação arquitetural
Falar que a documentação ajuda a melhorar a arquitetura facilita a comunicação é importante, mas um tanto abstrato. Dando “um passo à frente”, ficam evidentes três usos comuns para a documentação:
- Educação, seja para novos membros do time, analistas externos ou até mesmo um novo arquiteto.
- Alinhamento com stakeholders
- Base para a continuidade da construção e análise do software.
O esforço precisa ser compatível com o risco de falha no projeto. Cada projeto enfrenta diferentes riscos e não há uma única forma de fazer de arquitetura de software. É sempre necessário avaliar os riscos de cada projeto e aceitar que, eventualmente, a saída pode ser sequer fazer esforço para elaboração da arquitetura pois há tantos projetos similares anteriores bem-sucedidos que não haverá risco, desde que arquiteturas que deram certo sejam usadas como referência. (Fairbanks)
Em minha atuação como consultor é comum encontrar software, principalmente em empresas menores, sem qualquer tipo de documentação. Por outro lado, também não é incomum, principalmente em empresas maiores, encontrar documentação tão “abstrata” e desatualizada que não resolve dúvida alguma. Há tanta burocracia envolvida que toda informação relevante, quando há, fica escondida atrás de formatos e normas. Muitas vezes, as “dores” que geram a necessidade de consultoria são provenientes da falta de alinhamento do time sob aspectos básicos da arquitetura. Quase sempre, os problemas “se resolvem sozinhos” assim que se inicia o esforço para gerar documentação básica, porém de qualidade.
O que (geralmente) precisa ser documentado
Se a documentação é boa quando o custo de sua elaboração é compensado pela redução de custos em outras atividades ou pela mitigação de riscos, então, sua manutenção precisa custar o mínimo possível. De forma objetiva, a documentação de arquitetura útil para os projetos demanda atualizações menos frequentes.
A documentação arquitetural deve registrar, primeiro, aspectos que vão permanecer verdadeiros por mais tempo. Sem dúvidas, se encaixam nessa característica algum detalhamento das restrições e dos atributos de qualidade.
A documentação arquitetural também precisa dar ênfase na estratégia – padrão coerente para tomada de decisões – que irá autorizar mudanças. Ou seja, que critérios devem ser observados para determinar a necessidade de adicionar, remover ou substituir a implementação dos componentes.
Finalmente, a documentação também deve expor a estrutura atual e suas propriedades. Entretanto, quanto maior for a fragmentação de componentes de um software, por exemplo, em arquiteturas baseadas em microsserviços – extremamente dinâmicos e auto organizados, com estratégias de descoberta sofisticadas – menor será o incentivo para documentar suas interações. Nesses casos, o uso de ferramentas que permitam a “captura” da arquitetura-do-momento automaticamente, como, por exemplo, soluções APM é essencial.
Considerações sobre “Architecture Haiku”
George Fairbanks propôs a ideia do Architecture Haiku – uma descrição de design super concisa de uma página, rápida de construir.
A provocação é colocar um overview da arquitetura em uma única folha de papel A4. Assim, com menos espaços para indecisões ou prolongamentos. Eventualmente, pode não haver espaço para diagramas – o que à primeira vista parece loucura, mas talvez seja muito brilhante!
Com tão pouco espaço, escolher as informações certas a serem incluídas é extremamente importante. Aqui está o que Fairbanks recomenda:
- breve resumo da solução geral,
- uma lista de restrições técnicas importantes,
- resumo de alto nível dos principais requisitos funcionais,
- lista priorizada de atributos de qualidade,
- breve explicação das decisões de design, incluindo justificativa e compensações,
- lista de estilos e padrões arquitetônicos usados,
- apenas diagramas que adicionem significado além das informações já na página.
Considerações sobre ADRs (Architecture Decision Records)
Uma decisão arquitetural trata sempre de uma escolha de design relacionada a uma característica funcional ou não-funcional indiscutivelmente relevante, pois, geralmente, tem algumas das seguintes características:
- afeta os objetivos do negócio ou atributos de qualidade (como performance, disponibilidade, segurança, manutenabilidade, etc.)
- é difícil de ser desfeita (uma das quatro fontes da complexidade)
- implica em gastos ou economias consideráveis de tempo ou dinheiro (protip: tempo geralmente é um proxy para dinheiro)
- demandou, para sua formulação, considerável tempo e esforço do time, geralmente demandando provas de conceito e avaliação de trade-offs.
- é extremamente complexa podendo não fazer sentido em primeira análise, sem o background necessário.
Uma das coisas mais difíceis de rastrear durante a vida de um projeto é a motivação por trás de certas decisões. Uma nova pessoa que está entrando em um projeto pode ficar perplexa, perplexa, encantada ou enfurecida com alguma decisão passada. Sem compreender a lógica ou as consequências, essa pessoa tem apenas duas opções: aceitar cegamente a decisão ou mudá-la cegamente. (Nygard)
Uma prática que tem se tornado comum é documentar as decisões arquiteturais em registros (architectural decision records) em um arquivo de texto curto, mantidos no repositório do projeto, geralmente composto das seguintes seções:
- Título, curto e expressivo
- Contexto, descrevendo aspectos técnicos, políticos, sociais e específicos que impactam na decisão, preferencialmente em linguagem neutra.
- Decisão, expressando, em linguagem ativa, que caminho deve ser seguido.
- Status, visto que a decisão ainda pode ser uma proposta, estar implementada (aceita), ultrapassada (deprecated) ou revertida (superseded).
- Consequências, descrevendo o contexto geral resultante da decisão. Devem ser observados aspectos positivos, negativos e neutros.
ADRs é prática recomendada pela Toughtworks em seu famoso radar.
Muita documentação pode ser substituída por códigos e testes altamente legíveis. Em um mundo de arquitetura evolutiva, no entanto, é importante registrar certas decisões de design para o benefício dos futuros membros da equipe, bem como para supervisão externa. Registros de decisão de arquitetura leve é uma técnica para capturar decisões arquitetônicas importantes junto com seu contexto e consequências. Recomendamos armazenar esses detalhes no controle de origem, em vez de um wiki ou site, pois assim eles podem fornecer um registro que permanece sincronizado com o próprio código. Para a maioria dos projetos, não vemos razão para você não querer usar essa técnica. (Toughtworks)
Grandes jornadas são mais fáceis com um mapa…
Documentação elaborada na medida certa, de acordo com as complexidades e riscos de um sistema, reduzem o custo total de propriedade, simplificando, acelerando e potencializando as tomadas de decisão.
Nos próximos capítulos, iremos introduzir, aos poucos, alguns documentos arquiteturais úteis para a maioria dos projetos.
// TODO
Antes de avançar para o próximo capítulo recomendo as seguintes atividades:
- Relacione quais documentações arquiteturais você está habituado a utilizar.
- Pondere sobre os “gaps” de informação que precisa enfrentar rotineiramente em seu trabalho. Que informações entende que precisaram estar documentadas?
- Pondere sobre o quão fácil (ou difícil) é incluir alguém novo no seu time hoje. Como é feita a integração técnica?
Desafio fazer isso tudo em uma folha A4 😱
A3 talvez 😉
Talvez outro fator que atrapalhe na adoção de documentação é falta de uma ferramenta para que isso seja feito na empresa. Aqui onde trabalho, a quantidade de documentação gerada após a adoção do Confluence foi aumentada de forma significativa. Do ponto de vista arquitetural ainda é uma ferramenta que possui GAPs significativos, porém já traz a cultura de documentação para outros patamares.
Senti falta de dois tópico quando se fala em documentação de software que tem como objetivo agregar valor( manter-se viva):
=> Documentação Visual x Documentação Descritiva x Ambas(cada uma a seu tempo).
=> Teste de arquitetura (Mas isso não é documentação! Como diria Cortella. Será?)
Isso bem discutido e pensado pode se tornar uma convenção/sugestão para times que entendem a necessidade de documentar melhor suas decisões e evoluções(Building Evolutionary Architectures)!
Em resumo … deixar de lado a abstração de “talvez aqui isso, talvez ali aquilo” e sim sugerir abordagens como mencionado:
=> Mapas mentais;
=> C4 Model,
=> Haiku etc …
Obviamente depois de uma boa dose de curadoria 😉