Documentar é preciso (?) ...

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).

Por causa de um rigor difícil de justificar hoje em dia, era comum que se consumisse semanas elaborando documentações detalhadas, não apenas em nível arquitetural mas bem “perto do código”, para um esforço de implementação que iria durar apenas dias. A justificativa era uma pretensa garantia de qualidade que nunca se confirmava na prática. Felizmente, essa já não é mais a realidade, embora, talvez, hoje pequemos pelo contrário.

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)

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

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:

1. 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.
2. 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.
3. 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:

1. Educação, seja para novos membros do time, analistas externos ou até mesmo um novo arquiteto.
2. Alinhamento com stakeholders
3. 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, 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 versão do código-fonte, 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)

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.

Peça a alguém na indústria da construção para comunicar visualmente a arquitetura de um edifício e você será apresentado com plantas do local, plantas baixas, vistas de elevação, vistas de seção transversal e desenhos detalhados. Em contraste, peça a um desenvolvedor de software para comunicar a arquitetura de software de um sistema de software usando diagramas e você provavelmente obterá uma confusão confusa de caixas e linhas … notação inconsistente (codificação de cores, formas, estilos de linha, etc), nomenclatura ambígua , relacionamentos não rotulados, terminologia genérica, opções de tecnologia ausentes, abstrações mistas, etc.

Como uma indústria, temos a Unified Modeling Language (UML), ArchiMate e SysML, mas perguntar se eles fornecem uma maneira eficaz de comunicar a arquitetura de software é muitas vezes irrelevante porque muitas equipes já os descartaram em favor de caixas e linhas “diagramas. Abandonar essas linguagens de modelagem é uma coisa, mas, talvez na corrida pela agilidade, muitas equipes de desenvolvimento de software perderam a capacidade de se comunicar visualmente. (Simon Brown)

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?