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
 | Através desse trabalho, passamos a valorizar [..] Software em funcionamento mais que documentação abrangente; 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. Nygard |
O que a documentação arquitetural NÃO é
A documentação arquitetural trata das decisões de design com impacto determinante para o atendimento dos objetivos de negócio, respeito a restrições e atributos de qualidade.
Documentação arquitetural, finalmente, também não é documentação para usuários finais.
Documentação arquitetural e a comunicação
Comunicação é parte fundamental de qualquer atividade relacionada à engenharia de software. Quanto melhor (não necessariamente ampla) a comunicação, maiores as chances de que exista alinhamento de propósito e que autonomia de atuação seja possível. A documentação arquitetural é ferramenta para a comunicação em projetos de sistemas de software.Comunicação nem sempre é uma coisa boa
Skelton e Pais fazem uma advertência importante:
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.
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. |
(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.
Atividades suportadas pela documentação arquitetural
Falar que a documentação ajuda a melhorar a arquitetura e 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. 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, ferramentas que permitam a “captura” da arquitetura-do-momento automaticamente, como, por exemplo, soluções APM são essenciais.
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.
Decisões arquiteturais são realizadas durante todo o ciclo de vida de um software, com maior frequência em sua concepção e em pontos onde ocorrem mudanças sensíveis na escala ou escopo. Se não forem adequadamente documentadas, podem, no futuro, gerar comportamentos perigosos que coloquem em risco o sistema.
| 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, 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.
Considerações sobre notações gráficas informais
Muitos documentos arquiteturais incluem diagramas utilizando uma linguagem informal. Isso acontece, acredito, por um misto de preconceito e desconhecimento de linguagens formais como UML e Archimate.
Nesses diagramas, não é incomum, por exemplo, utilizar setas indicando algum tipo de relação entre elementos arquiteturais, não ficado claro, exatamente, que relação é essa.
No exemplo indicado:
- C1 “chama” C2?
- Dados de C1 são fornecidos para C2?
- C1 inicializa C2?
- C1 manda uma mensagem para C2?
- C1 é uma especialização de C2?
Apenas por esse breve exemplo é fácil concluir que diagramas construídos notações informais, como o indicado, podem perder um bocado de seu significado ao longo do tempo (muitas vezes, nem tanto tempo assim). Por isso, devem ser utilizados com reservas.
| Na corrida pela agilidade, muitas equipes de desenvolvimento de software perderam a capacidade de se comunicar visualmente. Simon Brown |
Considerações sobre a utilização de ferramentas de arquitetura corporativa
Ferramentas destinadas ao registro de arquitetura corporativa, se usadas apenas para o registro de artefatos de arquitetura de software acabam sendo, geralmente, soluções “pesadas”. Entretanto, não se pode ignorar que o uso adequado abre possibilidades interessantes como, por exemplo, a realização de consultas no repositório arquitetural respondendo questões como: “Que sistemas seriam afetados por um problema no servidor X?”, “Quais processos de negócio seriam impactados por modificações no software Y”, etc. Até mesmo indicações explícitas das integrações, tema do capítulo anterior, ficariam simplificadas.
Grandes jornadas são mais fáceis com um mapa…
As decisões de design que se relacionam com a arquitetura garantem o atendimento dos objetivos do negócio, respeitando restrições e atingindo atributos de qualidade. Entretanto, para que essas decisões cumpram seu papel, precisam ser rememoradas e compartilhadas com quem se juntar ao time ao longo do tempo. Tudo bem começar um projeto sem um mapa, mas é sempre bom ter um registro do caminho que foi percorrido e dos motivos para cada decisão.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.
Não faltam exemplos de empresas, com sistemas sólidos, porém com arquiteturas mal documentadas, que ficam “caros” para migrar para a nuvem por serem “caixinhas de surpresas”, onde desenvolvedores que os mantém são apenas íntimos desconhecidos que os herdaram de profissionais que há tempos não estão mais no time. Continuar sistemas sem os documentar beira a desonestidade.
Nos próximos capítulos, iremos introduzir, aos poucos, outros documentos e artefatos 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?
