Documento de arquitetura

Hoje, o assunto é a documentação arquitetural. Entendo que documentar a arquitetura tem duas grandes funções: comunicar formalmente as decisões tomadas, para nortear o desenvolvimento do software, e registrar para consultas futuras, resgatando o racional empregado.

A forma de documentar pode variar bastante, mas me agrada mais os formatos publicáveis em portais de documentação, exportando o conteúdo em HTML puro ou na modalidade WIKI, com marcações - que não deixa de ser uma variação do hipertexto tradicional. Essas formas são fáceis de se consultar e indexáveis.

O que colocar em um documento de arquitetura?

1- Eu gosto de começar com uma visão geral do problema e um diagrama, com o que é chamado de Big Picture, que mostra um panorama da solução técnica, comentando as principais características da arquitetura proposta. Normalmente se mostra um desenho com as camadas lógicas da aplicação, incluindo as ortogonais (cross cutting concerns), que tipicamente são resolvidas por injeção de código por aspectos.
2- Depois, aconselho usar uma seção com uma matriz de rastreabilidade, indicando o código do requisito atendido e o elemento arquitetural escolhido para atendê-lo. A matriz tem duas funções: uma espécie de índice alternativo para o documento e uma referência para análises de impacto/complexidade e/ou de risco de alterações futuras. Quando um requisito de negócio necessitar ser alterado, essa matriz dará a dica de quais pontos precisam ser alterados e (re)testados. Lembrar de incluir aqui referências para os requisitos não funcionais, premissas e restrições que precisam ser endereçadas pela arquitetura.
3- Visões arquiteturais devem descrever a arquitetura. Uma visão é uma espécie de ponto de vista do sistema, através da escolha de uma característica: pode ser a análise do modelo de dados, da implantação, do empacotamento, dos principais componentes ou classes, entre outras. Afinal, o sistema é muito complexo para ser analisado sob apenas um aspecto. Recomendo a leitura das publicações do Paulo Merson para aprender mais sobre visões e documentação arquitetural em geral.
Para cada visão, você deve criar pelo menos um diagrama e descrever as suas características. Uma visão pode ser desmembrada em outras, com maiores detalhes.
4- Registrar os mecanismos arquiteturais que permeiam a solução: como será feito o tratamento de exceções, as práticas de log para debug/trace da aplicação, se é necessário pensar em auditoria do sistema, criptografia empregada, como será feita a persistência e assim por diante. Você deve responder a algumas perguntas simples, como "qual o critério para registrar um log com nível warning" ou "qual o padrão para armazenar senhas no sistema".
5- Também recomendo uma matriz de dependências entre os elementos arquiteturais. Aqui, devem ser indicados quais elementos dependem de outros. Há vários tipos de dependências: entre visões, com diferentes graus de abstração, entre subsistemas, entre componentes, pacotes ou classes. O registro das dependências é de extrema importância, afinal, também ajuda na análise de impacto de mudanças.
6- Validações arquiteturais precisam ser planejadas e registradas aqui. Referenciar o roadmap arquitetural, indicando aqui como serão avaliadas as propostas de solução para a completa aderência aos requisitos. Devemos responder aqui, por exemplo, como avaliar se a proposta do cluster deve ser testada para garantir que atende ao requisito de disponibilidade, ou como o sistema será bombardeado por requisições para avaliar se suporta a carga prevista.
7- Registro das decisões tomadas, para lembrar porque uma solução candidata foi descartada. No CMMI, encontramos isso na process area Decision Analysis and Resolution (nível 3). Já comentei como isso deixa mais profissional o trabalho do arquiteto em outro post.
8- Se necessário, criar um glossário.

Esse é o resumo do que deve ser encontrado numa documentação arquitetural. Há inúmeras variações dessa proposta e, claro, precisam ser avaliadas e customizadas caso a caso. Nos próximos posts podemos detalhar melhor cada item desses. Além dessas dicas que tenho passado, há muitas referências excelentes na internet. Estude sempre, informe-se, avalie como outras pessoas lidaram com problemas semelhantes aos seus. Evite reinventar a roda, em especial para problemas que já contam com patterns para a resolução. Invista em arquitetura, para que o software fique bem estruturado. Sem isso, lá no futuro, esse software cobrará seu preço pela ausência de embasamento. Você não precisa passar por isso. Faça direito agora e tenha sossego na manutenção do seu sistema.

Provocações finais

No mundo do desenvolvimento ágil, preciso eu documentar a arquitetura? Ela não pode mudar com frequência e eu vou ficar perdendo tempo com o documento? O pessoal do manifesto ágil diz que é mais importante software funcionando que a documentação em ordem. Então, qual a motivação para perder meu precioso tempo com isso?
Preciso documentar tudo? Cada classe do meu sistema precisa estar no documento de arquitetura? (Essa última eu preciso responder: Não!)

Comentários

  1. Murilo, primeiramente gostaria de parabenizá-lo pela produção de conteúdo em seu blog.
    Este artigo ficou muito bom.
    Sobre os questionamentos finais, eu sou um defensor do mundo ágil, mas acredito que a documentação arquiterural é muito importante e, a funcional, dependerá da complexidade do problema e/ou valor de negócio.
    Não vejo problema, em desonvolvimento de software, mesclarmos o desenvolvimento tradicional com o desenvolvimento ágil.
    Acredito que nós profissionais de soluções de problemas, devemos​ focar em software de qualidade e que este seja solucionado, de fato.

    Um forte abraço,
    --
    Riba

    ResponderExcluir
    Respostas
    1. Meu caro Luciano Ribamar, obrigado por prestigiar o blog.
      Um dos objetivos desse post é justamente colocar o pessoal para pensar que, independente se a abordagem é ágil ou mais tradicional, devemos registrar as decisões tomadas. Esse esforço será pago quando houver manutenção e a documentação servirá como guia para evoluir o software de uma maneira melhor.

      Excluir

Postar um comentário

Postagens mais visitadas deste blog

Brilho nos olhos

Um breve olhar do que já foi escrito

Requisitos conflitantes e dilemas no projeto de software