A Arte de Trabalhar Diagramas Arquitetônicos

Em algum momento, em cada projeto de software em que estamos envolvidos, pode haver a necessidade de criar diagramas arquitetônicos. Quer estejamos seguindo um modelo arquitetônico formal (por exemplo Kruchten 4+1, Rozanski & Woods, etc) ou não, existe a necessidade de documentar algumas partes da aplicação através da criação de diagramas. Na arquitetura de software, tais diagramas são criados em conformidade com vistas que estão relacionadas a um ponto de vista específico que poderia ser parte de um modelo, mas no artigo atual prefiro me ater ao termo diagrama arquitetônico e não ser muito formal; todos os outros aspectos não pretendem ser cobertos aqui.

Baseada na minha experiência como arquiteto de software e treinador técnico, há muitas discrepâncias entre os projetos e dentro da equipe de projeto de desenvolvedor para desenvolvedor na forma como os diagramas arquitetônicos são criados. Eu vi muitos problemas de inconsistência, fragmentação e granularidade da informação renderizada e a aparência dos diagramas. Em comparação com um modelo arquitetônico que deve ser formal e padronizado, os diagramas podem não necessariamente ser formalizados ou seguir um padrão específico.

Não obstante, os diagramas devem ser auto-descritivos, consistentes, precisos o suficiente e conectados ao código. É por isso que é importante que todo arquiteto ou engenheiro de software confie em várias diretrizes ao criar diagramas arquitetônicos, uma vez que elas são a base comum da comunicação da arquitetura da aplicação ao longo do tempo (por exemplo, estrutura, elementos, relações, propriedades, princípios) e entre diferentes partes interessadas com vários antecedentes e preocupações técnicas.

Casos atuais ao projetar diagramas arquitetônicos

Antes de aprofundar em possíveis questões, eu gostaria de ter uma analogia com um idioma inglês que diz que “uma imagem vale por mil palavras”. Segundo esta explicação wiki, “refere-se à noção de que uma idéia complexa pode ser transmitida apenas com uma única imagem fixa ou que uma imagem de um sujeito transmite seu significado ou essência mais efetivamente do que uma descrição o faz”. O mesmo conceito se aplica a um diagrama arquitetônico: se ele levanta mais perguntas do que respostas, o diagrama não é bem criado. Não deixe um diagrama arquitetônico requerer milhares de palavras ou esclarecimentos!

Exemplo de um diagrama arquitetônico impróprio. Ele sofre a maioria dos problemas descritos abaixo

Vamos agora iterar através de uma lista de armadilhas que podem dificultar o processo de criação adequada de diagramas arquitetônicos.

O que denota uma caixa ou forma?

• Usar qualquer tipo de caixa ou forma que não esteja devidamente documentada pode causar múltiplas interpretações. Pode estar associado ou a um pedaço de dado, um monte de código, ou a um processo. Apenas uma simples caixa em um diagrama pode levantar múltiplas dúvidas e é muito importante evitá-las adicionando explicitamente detalhes sobre o significado da caixa ou forma na legenda do diagrama.

O que representam diferentes bordas de uma forma?

• Cada borda de uma forma (por exemplo, tracejada, pontilhada, etc.) pode ser mal interpretada no caso de um diagrama pobre. Uma borda específica refere-se a um tipo específico de componente (por exemplo, uma linha tracejada refere-se a um recipiente, um microserviço, uma camada, etc.), ou é apenas a preferência do designer ter uma aparência rica? Evite tal confusão, fornecendo detalhes precisos no diagrama de legendas ao escolher bordas múltiplas ou não padronizadas.

O que uma linha ou seta denota?

• Uma linha ou seta pode ser interpretada como um fluxo de dados (por exemplo, fluxos de dados do sistema A para o sistema B) ou como uma relação entre elementos (por exemplo, o componente A depende do componente B). Na maioria dos casos, as relações ou fluxos de dados representados por setas não convergem nas mesmas direções e é importante escrever isso explicitamente na legenda do diagrama.

Qual é o tipo de comunicação/associação indicada por uma linha ou seta?

• Even se a linha se refere a um fluxo de dados ou a uma relação entre componentes, o tipo de comunicação (por exemplo, no caso de fluxo de dados) ou o tipo de associação (por exemplo, no caso de relação) indicada por essa linha ou seta deve ser detalhada. Por exemplo, se a linha representa um fluxo de dados, a comunicação pode ser síncrona ou assíncrona, mas se a linha se refere a uma relação, ela pode ser representada por uma dependência, herança, implementação, etc. Todos esses detalhes devem estar presentes na legenda do diagrama.

O que significa essa cor?

• Diagrama de cores ‘perrot’ (por exemplo, várias cores para caixas, linhas) sem nenhuma intenção documentada apropriada pode levantar várias questões (por exemplo, por que algumas caixas são verdes e outras vermelhas? Porque é que algumas linhas são pretas e outras azuis?). O esquema de cores é menos importante em um diagrama, e usar um rico número de cores não traz muito conteúdo adicional ou informações valiosas. Um diagrama também poderia ser auto-explicativo e bem desenhado apenas usando cores pretas e brancas, a menos que haja uma restrição rigorosa para enfatizar algumas partes do diagrama, usando cores distinguíveis. Em qualquer caso, é sempre melhor ater-se à simplicidade em termos de cores usadas, mas se não for o caso, não se esqueça de detalhar a escolha.

Relações ausentes entre elementos do diagrama ou entidades isoladas

>
• Relações ausentes entre elementos ou entidades isoladas de um diagrama podem ser uma pista de incompletude. Tanto de uma perspectiva estrutural como comportamental, cada elemento ou entidade deve basear-se em / ter uma relação (representada por uma linha ou seta) com outra parte do sistema representada por um elemento diferente.

Siglas enganosas/undocumentadas ou termos demasiado vagos/genéricos

• Quando se utiliza uma etiqueta para um elemento de um diagrama, recomenda-se não utilizar qualquer sigla enganosa ou indocumentada que possa causar confusões. Apenas uma sequência de letras (ex. TFH, RBPM) não significa nada sem uma explicação adequada no elemento do diagrama ou, melhor ainda, na legenda do diagrama (ex. TFH – ticket feed handler, RBPM – rates business process manager).

• Uma outra característica dos elementos do diagrama relaciona-se com termos extremamente vagos ou genéricos (ex. lógica de negócio, lógica de integração) que não trazem muita informação valiosa porque os seus nomes não são devidamente auto-descritivos. Esta questão também pode residir no nível do código, e a sugestão seria sempre usar nomes auto explicativos e sugestivos, seguindo os princípios do código limpo.

Imprimir tecnologias, frameworks, linguagens de programação ou scripting, IDE ou metodologia de desenvolvimento em diagramas

• O design arquitetônico não está relacionado ou fundamentalmente baseado em qualquer tecnologia, framework, linguagem de programação ou scripting, IDE ou metodologia de desenvolvimento. Todos eles vêm mais tarde no processo para ajudar a construir a arquitetura, mas não são o ponto central. Eles não devem ser incluídos nos diagramas, mas sim declarados na descrição arquitetônica incluindo a lógica em torno da escolha deles.

Mix runtime e elementos estáticos no mesmo diagrama

• Elementos de runtime (por exemplo, threads, processos, máquinas virtuais, containers, serviços, firewalls, repositórios de dados, etc.) não estão presentes no momento da compilação e é recomendado evitar misturar esses elementos com os estáticos (por exemplo, componentes, pacotes, classes) no mesmo diagrama. Existem tipos de diagramas dedicados (por exemplo, diagrama de simultaneidade, diagrama de implantação) que são focados principalmente em elementos de tempo de execução e é importante distinguir entre estas duas categorias de elementos e evitar misturá-los o máximo possível.

Fazer suposições como “Vou descrever isto verbalmente”, e “Vou explicar mais tarde”

• Falta tudo o que não é descrito pelo próprio diagrama, e não há espaço para fornecer detalhes verbais para complementar um diagrama. Porquê? Porque todas as explicações mencionadas oralmente mas não capturadas no diagrama são perdidas, e mais tarde, quando alguns outros interessados (por exemplo, desenvolvedor, arquiteto) lerem o diagrama, eles não estarão cientes dessas explicações. Tente incluir todos os detalhes necessários em um diagrama para evitar qualquer necessidade de maiores esclarecimentos.

Níveis conflitantes de detalhes ou abstrações mistas

• Adicionar elementos relacionados a diferentes níveis de abstração no mesmo diagrama pode conflitar, uma vez que eles são vistos de diferentes perspectivas. Por exemplo, adicionar componentes a um diagrama de contexto arquitetônico ou classes a um diagrama de implantação pode divergir o propósito do próprio diagrama. Ao criar um diagrama, tente ficar com o mesmo nível de abstração.

Diagramas complicados ou muito vagos tentando mostrar muito ou insuficiente nível de detalhe

• “Tudo deve ser feito o mais simples possível, mas não mais simples” é uma citação bem conhecida pertencente a Albert Einstein. Isto é válido também para diagramas arquitetônicos; o nível e a granularidade da informação capturada deve ser significativamente eleito. Isto não é algo fácil; depende do modelo arquitetônico utilizado, da experiência do arquiteto e da complexidade do sistema.

Guia a seguir ao criar diagramas arquitetônicos

Parte as armadilhas acima, que devem fazer parte de uma lista de verificação de pré-requisitos para evitá-las, há também diretrizes gerais sobre como criar diagramas corretamente:

Selecionar o número ideal de diagramas

• Como disse Philippe Kruchten, “a arquitetura é uma besta complexa”. Usar um único plano para representar arquitetura resulta em uma confusão semântica ininteligível”. Para documentar sistemas modernos não podemos acabar com apenas um tipo de diagrama, mas ao criar diagramas arquitetônicos nem sempre é fácil escolher quais diagramas e quantos deles criar. Há vários fatores a serem considerados antes de tomar uma decisão; por exemplo, a natureza e a complexidade da arquitetura, as habilidades e a experiência do arquiteto de software, o tempo disponível, a quantidade de trabalho necessário para mantê-los e o que faz sentido ou é útil para atender às preocupações das partes interessadas. Por exemplo, um engenheiro de rede provavelmente vai querer ver um modelo explícito de rede incluindo hosts, portas e protocolos de comunicação; um administrador de banco de dados está preocupado com a forma como o sistema manipula, gerencia e distribui os dados, etc. Com base em todos esses aspectos, é recomendado pegar o número ideal de diagramas, seja qual for esse número.
• Se não houver diagramas suficientes (por exemplo, subdocumentados), partes da arquitetura podem estar escondidas ou não documentadas; por outro lado, se houver muitos (por exemplo, se houver um número muito grande de diagramas), é recomendável que o administrador de banco de dados se preocupe com a forma como o sistema manipula, gerencia e distribui os dados, etc. sobre-documentação), o esforço necessário para mantê-los consistentes, atualizados e não fragmentados pode aumentar consideravelmente.

Cerve a consistência estrutural e semântica entre diagramas

• Todos os diagramas devem ser consistentes com os outros em termos de caixas, formas, bordas, linhas, cores, etc. O aspecto estrutural deve ser o mesmo e cada parte interessada não deve ter dificuldades em entender os diagramas criados por diferentes desenvolvedores dentro de uma equipe. O ideal é que o diagrama se mantenha em uma ferramenta de diagramação comum e a reutilize em todos os projetos.
• Do ponto de vista semanal, todos esses diagramas devem ser sincronizados periodicamente com as últimas mudanças de código e entre eles, uma vez que uma mudança em um diagrama pode impactar outros. Este processo pode ser acionado manual ou automaticamente, utilizando uma ferramenta de modelagem. Este último é o mecanismo preferido, mas isto depende de projeto para projeto, em todos os casos a idéia é manter a consistência entre diagramas e código, independente do método ou ferramenta. Simon Brown disse que “os diagramas não são úteis para melhorar a arquitetura se não estiverem conectados ao código”, o que enfatiza a idéia de consistência semântica.

Prevenir a fragmentação dos diagramas

• Acontecer múltiplos diagramas pode tornar a descrição arquitetônica difícil de entender, mas também um esforço significativo para mantê-los. Como efeito colateral, a fragmentação pode aparecer (por exemplo, dois ou mais diagramas ilustram o mesmo atributo de qualidade – desempenho, escalabilidade, etc.). – mas cada um deles está individualmente incompleto). Nesses casos, recomenda-se ou remover os diagramas que não refletem atributos de qualidade relevantes (ligados a requisitos arquitetonicamente significativos) ou, melhor ainda, fundir diagramas (por exemplo, simultaneidade e implantação).

Keep traceability across diagrams

• Para poder verificar o histórico, também é importante fazer comparações entre diferentes versões de diagramas, além de reverter facilmente para uma versão anterior. Usar uma ferramenta de modelagem que não permita que isso possa ser um impedimento. As últimas tendências na indústria dependem do uso de uma linguagem de texto simples e intuitiva para gerar os diagramas a partir dela, o que parece resolver a preocupação de rastreabilidade. Outra vantagem dessa abordagem é que ela garante implicitamente uma consistência estrutural homogênea entre diagramas.

Adicionar legendas ao lado de diagramas arquitetônicos

• Se você não seguir uma linguagem padrão de descrição arquitetônica (por exemplo, UML, ArchiMate), detalhe cada peça do diagrama na legenda (por exemplo, caixas, formas, bordas, linhas, cores, acrônimos, etc).
• Se não for este o caso, na legenda basta adicionar a linguagem de descrição arquitectónica como chave e não há necessidade de explicações adicionais, uma vez que cada leitor irá seguir nessa linguagem específica para compreender o diagrama.

A linguagem de descrição arquitectónica (por exemplo, UML, ArchiMate, etc.) faz a diferença?

Há muitas opiniões sobre qual é a linguagem de descrição correcta a ser adoptada no projecto. Algumas pessoas podem argumentar que UML é rígido e não flexível o suficiente para modelar o projeto arquitetônico, um ponto de vista com o qual eu concordo. No entanto, em alguns casos pode ser mais do que suficiente para documentar os fundamentos de uma arquitetura sem depender de qualquer característica de extensibilidade UML, como perfis e estereótipos. Dando uma olhada em outras linguagens de descrição, podemos ver que o ArchiMate é mais poderoso e adequado para modelagem de sistemas empresariais em comparação com UML; há também o BPMN que é particularmente voltado para processos de negócios, etc. As comparações podem continuar, mas não pretendo fazer nenhuma revisão profunda sobre elas, já que este não é o objetivo deste artigo.

Dispor de uma linguagem de descrição arquitetônica abrangente e flexível o suficiente é um grande passo em frente e este deve ser um critério sólido ao escolhê-lo. Mas da minha perspectiva, a verdadeira causa reside em outro lugar e está relacionada ao fato de que a documentação arquitetônica não é criada de forma alguma. As pessoas muitas vezes acham a sua criação aborrecida, inútil ou inútil. O número de projetos de software sem, ou com documentação inadequada, é enorme. Eu não acho que as pessoas estejam criando intensivamente ou envolvidas na criação de diagramas arquitetônicos usando uma linguagem de descrição imprópria, e se eles fossem substituí-los por um melhor, os resultados seriam muito diferentes. Não, as pessoas não estão criando nenhuma documentação arquitetônica (incluindo diagramas arquitetônicos), e pior ainda, a maioria delas não tem idéia de como criá-la adequadamente. Estas são as coisas que precisamos abordar primeiro – para entender porque a documentação é importante e como criá-la adequadamente (através do treinamento de engenheiros de software); então a seleção de ferramentas apropriadas vem naturalmente.

Como os diagramas podem ser mantidos atualizados à medida que o sistema é desenvolvido, e as mudanças na arquitetura se materializam

Existem poucas abordagens para manter os diagramas atualizados; abaixo vou expressar três delas. A primeira opção, e a mais fácil, seria gerar automaticamente diagramas a partir do código-fonte, que é a verdade do terreno. Isto garante que todos eles são consistentes com o código. Infelizmente, com as ferramentas existentes isto ainda não é totalmente possível (pelo menos que eu saiba), já que as ferramentas reais não podem criar nenhum tipo de diagrama preciso e significativo apenas baseado no código fonte, sem intervenção manual significativa. Len Bass disse que “o ambiente de desenvolvimento ideal é aquele para o qual a documentação está disponível essencialmente livre com o apertar de um botão”, implicitamente a geração automática dos diagramas, mas ainda não chegamos a esse ponto.

A segunda abordagem seria projetar primeiro os diagramas usando uma ferramenta dedicada que depois gerasse os esqueletos do código fonte (por exemplo, componentes/pacotes com limites, APIs) usados mais tarde pelos desenvolvedores para preencher o código. Desta forma, toda mudança na arquitetura precisa ser acionada a partir do próprio diagrama, que automaticamente pode regenerar ou atualizar o esqueleto do código.

O último caso envolve a atualização manual dos diagramas toda vez que uma nova funcionalidade – que tem um impacto no projeto arquitetônico – é implementada. Para ter certeza que todas as mudanças de código são refletidas nos diagramas, é recomendado que a atualização dos diagramas seja parte da definição de feito no processo de desenvolvimento. Este cenário é menos recomendado porque poderia facilmente causar diagramas desatualizados ou inconsistentes (por exemplo, desenvolvedores muitas vezes esquecem ou não estão com disposição para atualizar diagramas) e infelizmente isto ainda acontece na maioria dos projetos.

Tendo em conta as ferramentas existentes, minha recomendação é ter uma mistura; para misturar automaticamente e manualmente criar diagramas. Por exemplo, tente gerar diagramas automaticamente, que podem ser razoavelmente renderizados por ferramentas baseadas no código fonte sem muito ruído (por exemplo, informações muito desordenadas ou sem sentido). Nesta categoria podemos incluir tanto diagramas com um alto grau de volatilidade (por exemplo, mais propensos a mudanças freqüentes de desenvolvimento, geralmente com uma abstração menor) ou, ao contrário, diagramas estáticos. Alguns desses diagramas podem se referir a diagramas de contexto, diagramas de arquitetura de referência, diagramas de pacotes, diagramas de classes, diagramas de entidades, etc. No entanto, em alguns casos, não é óbvio baseado apenas no código fonte como o sistema atende a alguns atributos de qualidade (por exemplo, disponibilidade, escalabilidade, performance), portanto a criação automática de diagramas não é uma opção suficiente. Ela precisa ser complementada por diagramas modelados manualmente. Alguns exemplos de tais diagramas incluem diagramas de seqüência, diagramas de estado, diagramas de simultaneidade, diagramas de implantação, diagramas operacionais, etc.

Que complicações (ou simplificações) surgem para os diagramas arquitetônicos quando se trata de arquiteturas modernas (e.por exemplo, microserviços)?

Microserviços ou qualquer outro estilo arquitetônico moderno (por exemplo, sem servidor, acionado por eventos) apenas conduz a estrutura do sistema, como os componentes se comunicam entre si (por exemplo, relações entre eles) e que princípios os governam. Pessoalmente, eu não acho que o estilo arquitetônico deva mudar a lógica ou conceitos em torno da criação dos diagramas (e implicitamente a descrição arquitetônica), nem o que eles devem capturar. No entanto, quando falamos de arquiteturas de sistemas modernos, geralmente com níveis de complexidade mais elevados em comparação com sistemas antigos e clássicos (por exemplo, monólitos), eles definitivamente têm um impacto na descrição arquitetônica e implicitamente nos diagramas, no sentido de que há múltiplas considerações a serem consideradas. Tais considerações podem ser em relação à compreensão do número de componentes distribuídos (por exemplo, micro-serviços distribuídos), o tipo de cada componente, como os componentes comunicam entre si (por exemplo, limites, APIs, mensagens), seu ciclo de vida e quem é dono de cada componente.

Tendo tudo isso em conta, visões que capturam a decomposição, desenvolvimento, implantação e operabilidade do sistema devem ser consideradas por padrão. Imagine um sistema com um número impressionante de micro-serviços, por exemplo; nesse caso, o número de diagramas pode aumentar significativamente porque cada micro-serviço pode acabar tendo o seu próprio conjunto de diagramas. Questões relativas à consistência (por exemplo, mudar a API de um serviço impacta outros X serviços, portanto todos os diagramas impactados precisam ser atualizados), fragmentação (por exemplo, a alta disponibilidade ou desempenho entre serviços distribuídos não está consolidada em um diagrama) ou preocupações transversais (por exemplo, quem está encarregado de ilustrar, de forma consolidada, aspectos como monitoramento ou segurança através de elementos inteiros do sistema) podem não ser facilmente tratadas. Além disso, pode haver desafios relacionados à coexistência e colaboração de equipes durante o desenvolvimento do projeto, e mesmo depois, a fim de mantê-lo.

Para resumir, sistemas modernos com arquiteturas complexas podem trazer preocupações adicionais que podem levar a complicações, mesmo no nível dos diagramas.

Sobre o Autor

Ionut Balosin é um Arquiteto de Software e Treinador Técnico Independente. Ele é um orador regular em conferências e encontros de desenvolvimento de software ao redor do mundo, realizando apresentações, cursos de treinamento e workshops. Para mais detalhes, consulte o seu website.