BT

Início Artigos Por que precisamos de diagramas de arquitetura?

Por que precisamos de diagramas de arquitetura?

This item in japanese

Favoritos

Pontos Principais

  • Criar e manter diagramas de arquitetura para fornecer conteúdo preciso e valioso não é fácil. Na maioria das vezes, criamos documentação demais, muito pequena ou irrelevante, porque não conseguimos identificar os beneficiários adequados e suas reais necessidades.
  • Um dos maiores erros é criar diagramas de arquitetura detalhados para partes do sistema com alta volatilidade. É um fardo mantê-los manualmente, a menos que sejam gerados automaticamente.
  • Na prática, a maioria das partes interessadas não está interessada em diagramas detalhados, mas sim em um ou dois diagramas de alto nível que refletem a modularidade e os limites do sistema. Além disso, para um entendimento mais profundo, o código deve ser a fonte da verdade, que na maioria dos casos apenas os desenvolvedores estão interessados.
  • Para encontrar a quantidade apropriada e a qualidade dos diagramas de arquitetura, faça um brainstorm e combine com a equipe o que é realmente útil para eles, seja lá o que isso signifique! Não tente criar diagramas para coisas auto-explicativas no código-fonte ou para qualquer metodologia de arquitetura muito abrangente.
  • O principal objetivo dos diagramas de arquitetura deve ser o de facilitar a colaboração, aumentar a comunicação e fornecer visão e orientação.
  • Desenhe um ou dois diagramas de alto nível na parede e use-os durante as reuniões (stand-ups, etc). Você, como arquiteto, deve torná-los visíveis, valiosos e parte da cultura do projeto. Não os mantenha ocultos ou em locais menos acessíveis para as partes interessadas.

Tentamos criar diagramas de arquitetura (como parte da documentação técnica) com o objetivo de refletir o estado interno de uma aplicação, mas na maioria das vezes não o fazemos corretamente. Os diagramas resultantes podem variar de muito abrangentes a extremamente vagos. Às vezes, os diagramas são simplesmente irrelevantes. Eu escrevi anteriormente algumas dicas sobre como criar diagramas arquiteturais úteis.

Mesmo quando diagramas relevantes são criados, raramente mantemos essa documentação atualizada com o recurso que está sendo desenvolvido como parte de um processo de desenvolvimento contínuo integrado. Na realidade, a documentação é atualizada apenas de tempos em tempos, provavelmente durante alguns sprints (quando há tempo para tal atividade), ou para um lançamento específico. Por outro lado, a maioria dos desenvolvedores com os quais eu interagi (colegas ou alunos que frequentam meu curso de Arquitetura de Software) não são a favor da criação e manutenção de documentação técnica; eles consideram tedioso, demorado e menos valioso do que outros trabalhos, ou mesmo desnecessários quando o código-fonte é suficiente. Embora sempre haja exceções, tenho certeza de que, quando se trata de diagramas de arquitetura, as coisas são praticamente as mesmas na maioria dos projetos.

O que fazemos de errado e como podemos melhorar?

Em primeiro lugar, é importante entender quem são os verdadeiros beneficiários dos diagramas de arquitetura e da documentação técnica. A quantidade e a qualidade da documentação devem refletir com as necessidades das partes interessadas, pois só assim podemos criar documentação precisa e suficiente.

O principal beneficiário deve ser a equipe (desenvolvedores, engenheiros de teste, analistas de negócios, devops, etc.) que tenham envolvimento direto no projeto. Na minha experiência, fora da equipe, há muito poucos interessados que realmente se importam com a documentação. No melhor dos casos, eles podem estar interessados em um ou dois diagramas de alto nível (por exemplo, o diagrama de contexto, aplicação ou um diagrama de componente de software) que descrevem aproximadamente a estrutura do sistema e fornecem uma compreensão de alto nível do mesmo.

No entanto, na maioria das vezes, falhamos em identificar os verdadeiros beneficiários e suas reais necessidades e tentamos criar muita documentação. Isso rapidamente se torna um fardo para manter e logo fica desatualizado. Em outros casos, simplesmente omitimos a criação de qualquer tipo de diagrama, porque não há tempo, nenhum interesse específico ou ninguém quer assumir essa responsabilidade. Além disso, o Manifesto Ágil prescreve que as equipes valorizem o software funcionando sobre documentação abrangente, o que desestimula processos de documentação complicados.

Para encontrar o equilíbrio adequado do nível de documentação correto, experimente este exercício em sua equipe:

  • Pergunte a cada um de seus colegas o que eles realmente precisam da documentação técnica e que tipos de diagramas devem ser incluidos;
  • Colete as opiniões, e então debata e concordem em conjunto sobre o que é realmente necessário para a equipe. Pode haver um ou dois participantes influentes fora da equipe com solicitações extras, e é responsabilidade do arquiteto levar em consideração suas necessidades;
  • Com base nisso, crie a quantidade e o nível adequados de documentação técnica que atendam às necessidades das partes interessadas. Se os desenvolvedores entenderem o valor real da documentação e tiverem como interesse o valor restante, eles serão incentivados a contribuir e mantê-la adequadamente.

No final, todo mundo fica feliz. No entanto, se os desenvolvedores não entenderem a necessidade ou não se importarem, você quase poderá esquecê-la, pois a documentação torna-se muito difícil de ser mantida por uma única pessoa (o arquiteto) quando essa deve ser uma responsabilidade compartilhada entre os membros da equipe.

No passado, em projetos em cascata, criamos muita documentação derivada de metodologias abrangentes de arquitetura corporativa (intencionalmente, não nomeie nenhuma delas) ou solicitadas por alguns arquitetos de torres de marfim. Quando as metodologias ágeis eram adotadas em grande escala em projetos de software, um grande mal-entendido comum era que as pessoas achavam que não precisavam de documentação, porque o software funcional é mais importante do que criar uma documentação abrangente. Esses são os dois casos extremos, é claro. Não há metodologia precisa ou processo científico para abordar explicitamente a quantidade apropriada de documentação para um projeto. Todas as metodologias atuais de arquitetura de software são recomendações ou diretrizes puras. Esses processos arquiteturais abrangentes seguidos no passado são hoje em dia substancialmente simplificados e inexistentes nos projetos. Isso não significa que devemos criar menos documentação ou nenhuma documentação, mas sim focar na criação de documentação que ofereça valor real e, ao mesmo tempo, não atrapalhe o progresso da equipe. Além disso, nem toda documentação fornece valor. Mas isso não é o mesmo que "toda a documentação não fornece nenhum valor". Além disso, o que faz sentido para um projeto pode ser menos relevante para outro devido a um contexto diferente (por exemplo, econômico, político, etc.), metas comerciais, partes interessadas etc.

Nestas circunstâncias, é muito difícil obter a resposta certa para a pergunta: qual é a quantidade adequada de documentação técnica (por exemplo, os diagramas de arquitetura)? No final, relaciona-se a cada projeto e à experiência do arquiteto e pode ser resumido como "DEPENDE". A quantidade certa de documentação para fornecer valor depende do que sua equipe decidiu que precisa. Meu conselho é decidir junto com a equipe e criar documentação técnica suficiente, seja lá o que isso signifique para sua equipe. Se nenhuma documentação faz sentido para o seu projeto (porque não !?), isso pode ser aceitável. Documente a lógica por trás desse acordo de equipe e torne-o transparente para todos os envolvidos. Se houver dois ou três diagramas de interesse real, verifique se eles estão atualizados, consistentes e sempre refletem o estado do sistema. Não se concentre em mais nada que possa não trazer qualquer valor.

Mas… e para que precisamos de documentos de arquitetura?

Os diagramas arquiteturais em particular e a documentação, em geral, devem ser usados principalmente para colaboração, comunicação, visão e orientação dentro da equipe e entre as equipes. Também deve incluir as decisões significativas de projeto no projeto (tomadas em um determinado momento), mas nada mais.

Diagramas arquiteturais devem ajudar a todos a ver o panorama e entender o ambiente. Na minha opinião, esta deve ser a razão fundamental por trás da criação e manutenção dos diagramas arquiteturais.

Por exemplo, os diagramas de contexto atendem perfeitamente a essa necessidade e fornecem um grande nível de detalhes sobre os limites do sistema, observando o panorama geral. Isso ajuda a equipe a ter um entendimento comum e facilita a comunicação entre diferentes partes interessadas. Participei de muitas reuniões quando esse diagrama de contexto, apresentado na tela grande, economizava muitas perguntas e removia as incertezas sobre a arquitetura do sistema de alto nível.

No entanto, muitas vezes tentamos criar uma documentação abrangente para refletir o estado interno do sistema. Isso pode assumir a forma de diagramas de estado, diagramas de atividades, diagramas de classes, diagramas de entidade, diagramas de concorrência, etc. Mas eles rapidamente ficam desatualizados, a menos que sejam automaticamente gerados a partir do código-fonte por algumas ferramentas "mágicas".

Qual seria o propósito de criar diagramas tão detalhados se as pessoas não precisassem ler, ou talvez entendê-las? Diagramas abstratos para as partes interessadas nos negócios são mais do que suficientes. Para os desenvolvedores, na maioria dos casos, o código-fonte (ou seja, uma fonte única da verdade) é o que eles realmente precisam para entender a aplicação. Então, por favor, pare de criar diagramas para coisas que são auto-explicativas no código, muito detalhadas, ou quando não há audiência real.

Crie diagramas de arquitetura significativos, mas mínimos, e os incorpore na documentação técnica. Para a maioria das aplicações, provavelmente são necessários dois ou três tipos de diagramas significativos. Os mais comuns são diagramas de contexto, diagramas de componentes da aplicação/software, diagramas de sistema ou diagramas de implantação.

Meu exemplo prático

Em meus projetos na maioria das vezes, eu utilizo dois tipos de diagramas:

Diagramas de contexto

Diagramas de aplicação ou de componentes de software

Por favor, trate esses diagramas como exemplos simples, mostrando algumas orientações sobre um nível razoável de informações que cada diagrama deve fornecer. As informações que constam em um diagrama devem ser relevantes para o nível de abstração correspondente, mas também devem atender às necessidades das partes interessadas.

Na prática, pode ser tentador adicionar mais e mais detalhes a um diagrama, mas se eles não são realmente úteis para os beneficiários, isso leva a um ruído extra, maior manutenção e ao risco de estar desatualizado.

Especificamente para os diagramas dos exemplos, incluindo os detalhes como protocolos e formato de dados, podem ser muito úteis para os interessados ​​técnicos, já que são um detalhe de implementação necessário. No entanto, como também declarado neste artigo, não existe uma metodologia precisa para descrever explicitamente a quantidade apropriada de detalhes que um diagrama deve incluir. Isso realmente depende de projeto para projeto, no entanto, o arquiteto deve identificar o que é realmente útil para as partes interessadas e criar e manter os diagramas para refletir adequadamente isso.

Para qualquer detalhe adicional além desses diagramas, eu poderia encontrá-lo no código-fonte ou gerá-lo automaticamente por algumas ferramentas (por exemplo, diagramas de visão, de tempo de execução, diagramas de visão de desenvolvimento, diagramas de visão do sistema ou infra-estrutura etc.).

Eu também desenho o diagrama de arquitetura de software (incluindo todos os componentes da aplicação) durante a reunião onde todos estão na sala. Durante os nossos stand-ups e outras reuniões, as pessoas falam sobre suas tarefas, status e impedimentos enquanto apontam para este diagrama na parede. Dessa forma, todos os membros da equipe, desde o dono do produto até o desenvolvedor, compreendem e enxergam o quadro geral e prevêem os obstáculos gerais e outros desafios de integração. Além disso, oferece um status de progresso mais preciso durante a sprint para toda a equipe, especialmente quando a arquitetura é distribuída e há dependências entre as pessoas.

Eu aconselho você a fazer o mesmo para sua equipe. Continue aumentando a colaboração, a comunicação, a visão e a orientação usando apenas diagramas arquiteturais suficientes e pare de criá-los por qualquer outro motivo, especialmente se a equipe não os usar. Criar e manter manualmente diagramas para refletir o comportamento do código é, na maioria dos casos, uma perda de tempo. Ao fazer isso, você pode ficar tentado a adicionar mais e mais diagramas conforme a evolução do código-fonte, o que é uma armadilha perigosa. Em vez de criar um número exaustivo de diagramas, mantenha dois ou três que descrevem o sistema a partir de diferentes níveis de abstrações e são realmente necessários para a equipe. Mantenha-os sempre atualizados; essa tarefa é facilitada quando não contém muitos detalhes e faz parte da cultura da equipe.

Além disso, lembre-se de que a equipe deve ser a principal beneficiária dos diagramas de arquitetura. Se eles não manifestarem nenhum interesse, provavelmente você deve parar de criá-los; Pode ser uma perda de tempo. Não devemos criar diagramas arquiteturais apenas "para o propósito de tê-los", seguir algumas metodologias abrangentes ou justificar nosso papel como Arquitetos.

Sobre o autor

Ionut Balosin é Arquiteto de Software e instrutor técnico independente. Ele é um apresentador regular em conferências e encontros de desenvolvimento de software em todo o mundo, oferecendo apresentações, cursos, treinamento e workshops. Para mais detalhes, por favor, verifique seu site.

Avalie esse artigo

Relevância
Estilo/Redação

Olá visitante

Você precisa cadastrar-se no InfoQ Brasil ou para enviar comentários. Há muitas vantagens em se cadastrar.

Obtenha o máximo da experiência do InfoQ Brasil.

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

Comentários da comunidade

  • Ferramenta utilizada.

    by Guilherme Marcial /

    Seu comentário está aguardando aprovação dos moderadores. Obrigado por participar da discussão!

    Qual a ferramenta foi utilizada ou recomenda para representar as arquiteturas de forma visual?

    Abraços.

  • Re: Ferramenta utilizada.

    by Marcelo Costa /

    Seu comentário está aguardando aprovação dos moderadores. Obrigado por participar da discussão!

    Fala Guilherme, blz?

    Eu sou consultor e costumo recomendar o uso do modelo C4 como linguagem de modelagem. Ela é bem simplificada e consegue atender bem. Dá uma lida neste outro artigo aqui: www.infoq.com/br/articles/C4-architecture-model

    Abraços,

    Marcelo

  • Re: Ferramenta utilizada.

    by Guilherme Marcial /

    Seu comentário está aguardando aprovação dos moderadores. Obrigado por participar da discussão!

    Blz, Marcelo!

    Cogitei exatamente essa, obrigado!

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

BT

Seu cadastro no InfoQ está atualizado? Poderia rever suas informações?

Nota: se você alterar seu email, receberá uma mensagem de confirmação

Nome da empresa:
Cargo/papel na empresa:
Tamanho da empresa:
País:
Estado:
Você vai receber um email para validação do novo endereço. Esta janela pop-up fechará em instantes.