Como documentar a Arquitetura de Software

Veja neste artigo uma introdução sobre como documentar os principais aspectos técnicos relativos ao desenvolvimento de um sistema.

por Flávio Secchieri Mariotti

Introdução

No ciclo de vida do desenvolvimento de software podemos encontrar diversas etapas e todas com seus propósitos muito bem definidos, porém, uma que podemos dizer com segurança ser de extrema importância é a arquitetura do software.

Quando falamos em arquitetura logo nos vem alguns padrões como Zechman framework, TOGAF, DODAF e etc. Esses padrões existem para auxiliar e facilitar a arquitetura corporativa no intuito de prover uma abordagem ao design, planejamento, implementação e governança de uma arquitetura de informação corporativa.

Mas hoje em dia, com o conceito de agilidade sendo um dos principais diferenciais no desenvolvimento de software, como implementar uma arquitetura robusta com uma documentação simples e eficiente? Na tentativa de responder a essa pergunta, esse artigo irá apresentar uma forma simples e eficiente para documentar a arquitetura dos seus sistemas.

O que é Arquitetura de Software?

A arquitetura de software é uma descrição do sistema que auxilia na compreensão de como o sistema irá se comportar.

Arquitetura é um meio de se obter uma análise antecipada para garantir que a abordagem de design apresentada, produzirá um sistema que alcance os requisitos exigidos pelo cliente, tais como: desempenho, segurança, disponibilidade, integridade, flexibilidade e etc. Portanto, uma arquitetura de software consiste na definição de suas camadas, que podem envolver entidades como: componentes de software, aplicativos externos, sistemas legados e propriedades externas.

Por que devo documentar a arquitetura do sistema?

Segundo Steuart Henderson Britt, "Fazer negócios sem publicidade ou projetar uma arquitetura sem documentar, é como piscar para uma garota no escuro. Você sabe que está fazendo, mas ninguém mais sabe."

Acho essa frase engraçada, porém demonstra a verdadeira necessidade de uma documentação. Por mais perfeita e adequada que seja sua arquitetura, será inútil para outras pessoas que não a conhecem e que não podem entendê-la bem o suficiente para manuseá-la. Portanto, a documentação se faz essencial para todos os casos.

Na maioria das vezes, a documentação é tratada como algo secundário, algo que as pessoas fazem porque são obrigadas por um contrato ou gerente que a exige. Estas podem, sim, ser razões legítimas para se documentar algo, porém, não pode faltar a seriedade e comprometimento do arquiteto ao desenvolver esse documento, garantindo o valor e serenidade do mesmo.

Estrutura do documento

· Histórico de revisões

· Introdução

· Visão geral

· Requisitos não-funcionais

· Mecanismos arquiteturais

· Fundamentação

· Visão de casos de uso

· Componentes

· Implantação

Entendendo sua estrutura

Nesta parte do artigo vamos entender, detalhar e ver alguns exemplos para documentar cada fase apresentada na estrutura do documento.

1. Histórico de revisões: alguns dos principais objetivos que essa fase do documento pretende alcançar são: deixar explícito cada alteração feita no documento; controlar a versão do documento; deixar explícito o responsável pela alteração; controlar a veracidade do documento.

Exemplo:

DATA	VERSÃO	DESCRIÇÃO	AUTOR
11/12/2011	1.0	Documento inicial	Flávio Mariotti
03/01/2012	1.1	Alteração no item 3	Nome do autor

2. Introdução: nesta fase do documento, o responsável deve apresentar de forma clara a objetividade do trabalho a ser documentado. De forma sucinta, descrever do que se trata o documento e quais assuntos serão abordados no mesmo.

3. Visão geral: a fase visão geral do documento, tem como objetivo, demonstrar de forma sucinta, os principais elementos que compõe a arquitetura do sistema. Geralmente essa etapa é apresentada com uma figura que deve servir como referência inicial para qualquer entidade que tenha ou pretende entender o sistema tecnicamente.

Exemplo:

Figure 1. Imagem que representa a visão geral no documento.

4. Requisitos não-funcionais: nesta fase do documento, é necessário listar os requisitos não funcionais encontrados no sistema, tais como: portabilidade, usabilidade, desempenho e etc. O objetivo é colocar o nome do requisito e descrever com detalhes suas características.

Exemplo:

5. Mecanismos arquiteturais: nesta fase do documento, devemos listar os mecanismos arquiteturais encontrados no sistema, ou seja, identificar todos os mecanismos de análise, mecanismo de design e mecanismo de implementação. O intuito desta etapa é verificar e garantir que todas as preocupações técnicas relativas à arquitetura do sistema tenham sido capturadas.

Exemplo:

6. Fundamentação: nesta fase, o arquiteto deve fundamentar todas as decisões importantes de design. Além disso, deve descrever as alternativas significativas rejeitadas no projeto. Esta seção pode indicar hipóteses, restrições, resultados de análises e experiências significativas para a arquitetura.

7. Visão de caso de uso: esta fase, será responsável por apresentar os casos de uso ou cenários escolhidos para a validação da arquitetura apresentada. Casos de uso, backlog, requisitos de usuários ou qualquer outro nome que represente os itens relevantes para o funcionamento do sistema final, o intuito é exercitar e testar os principais aspectos de risco da arquitetura.

Exemplo:

8. Componentes: nesta fase, o arquiteto deve apresentar o diagrama de componentes. É recomendado como boas praticas de mercado o uso do modelo UML para criação do diagrama, que deve apresentar os possíveis componentes e suas dependências. Além disso, o arquiteto deve criar uma tabela detalhando as responsabilidades de cada componente.

Exemplo:

Figure 2. Representação gráfica com diagrama UML para  representar os componentes.

9. Implantação: nesta fase, o arquiteto deve descreve as configurações de distribuição dos componentes de software na área física em que serão implantados.

Exemplo:

Figure 3 Representação de um cenário para implantação

Conclusão

Existem diferentes maneiras e padrões para documentação da arquitetura de software, porém, podemos concluir com esse artigo, que o importante é criar um documento que descreve com clareza os principais aspectos envolvidos no escopo do sistema.

Além disso, podemos perceber que podemos customizar a documentação de forma que ela se torne exequível para realidade de cada projeto. O importante é documentar com seriedade e comprometimento com o seu trabalho.

Dicas

Para aqueles apaixonados pelo assunto, vale a pena dar uma olhada no seguinte portal. http://www.sei.cmu.edu/architecture/

Comunicado Importante

Espero que tenham gostado do conteúdo explorado neste artigo. Caso exista qualquer dúvida relacionada ao conteúdo ou interesse em conhecer um pouco mais sobre Arquitetura de Software ou Documentações, informe seu interesse usando o recurso de "comentários".

Referência

Peter Eeles; Peter Cripps. The Process of Software Architecting, Addison-Wesley Professional, 2009.

Paul Clements; Felix Bachmann; Len Bass; David Garlan; James Ivers; Reed Little; Paulo Merson; Robert Nord; Judith Stafford. Documenting Software Architectures: Views and Beyond, Second Edition, Addison-Wesley Professional, 2010.