C4 Model
Um modelo de documentação para diferentes públicos, fácil de fazer e entender.
O que é C4 Model?
Criado por Simon Brown, o modelo C4 é um conjunto de diagramas hierárquicos baseado em camadas que pode ser usado para descrever a arquitetura de um software em diferentes níveis de abstração e conforme aumenta a profundidade, maior será o nível de detalhes.
E por que documentar?
Muitas vezes sua elaboração necessita de um tempo significativo, tempo este que pode ser considerado dispensável, pois em muitos casos ela não é usada com frequência, além de a documentação técnica ser constantemente cansativa para ler e entender. E afinal, com o surgimento do desenvolvimento ágil a documentação se tornou desnecessária. Bom, se você interpretou assim, você não prestou atenção no manifesto que diz:
“Software em funcionamento, mais que documentação abrangente”.
É verdade que gerar uma documentação extensiva pode não trazer grandes benefícios, porém posso apresentar alguns motivos e situações em que tê-la pode te ajudar a resolver alguns problemas de comunicação, facilitar sua vida e tornar seu trabalho mais ágil.
- Registrar requisitos do sistema para auxiliar a construção da arquitetura, desenvolvimento e métricas de acompanhamento.
- Manter a objetividade e responsabilidade do Software, principalmente em um estrutura de microsserviços.
- Auxílio na compreensão do software e integração de novos membros do time
- Facilita a manutenção e evolução do software dispensando o remapeamento para novas implementações.
- Valor agregado. Por todos os pontos citados ter uma documentação de qualidade entrega valor ao demonstrar o nível de maturidade / responsabilidade do time, auxilia a resolver alguns problemas de comunicação e pode tornar o trabalho mais ágil — especialmente quando uma reunião pode ser transformada em um e-mail com um link ;) .
E você pode estar pensando: Ok, entendi. Me convenci com os benefícios, mas o lado ruim me desanima. Como ter uma documentação de qualidade e não perder tempo produzindo arquivos extensos?
Tenho uma resposta que pode te desanimar um pouco mais, e ela é DEPENDE. Depende do seu sistema, do nível de complexidade, do nível de certeza, da fase do software, então… depende. Você vai precisar encontrar o ponto de equilíbrio e o que funciona no seu time e/ou sua organização. E o C4 pode ser uma boa alternativa de documentação.
Como o C4 me ajuda?
O modelo C4 é uma documentação visual com padronização simples, possui diagramas baseados em mapas com textos curtos e objetivos que podem ser apresentados tanto para a área de negócios, quanto para o time técnico.
Imagine que estamos usando o Google Maps com zoom suficiente para ver o continente sul americano, nesta distância o mapa irá mostrar o Brasil — como uma unidade — e suas fronteiras. Se dermos um zoom no mapa poderemos ver um estado, ampliando o zoom será possível ver uma cidade, e se expandir um pouco mais será possível ver as ruas desta cidade. O C4 usa o mesmo conceito, quanto maior o nível, maiores serão os detalhes apresentados.
O nome deste modelo de documentação vem da quantidade de camadas e seus nomes: Contexto, Container, Componentes e Código. A seguir cada nível será descrito juntamente com um diagrama modelo de um sistema bancário via Internet fictício desenvolvido por Simon Brown para ilustrar o modelo C4.
Nível 1: Contexto
O primeiro nível tem o objetivo de exibir o quadro geral, possibilitando visualizar as fronteiras e os relacionamentos com cada item externo. O sistema é representado em uma caixa ao centro como uma unidade (assim como o Brasil no exemplo anterior) e ao seu redor todos os outros itens com o qual interage.
Neste ponto os detalhes não são importantes, o principal é o contexto em que o software está inserido, exibindo os sistemas e usuários com os quais há comunicação, pode ser apresentado para qualquer tipo de público.
A imagem acima apresenta um sistema bancário via internet (representado no centro) onde um cliente pode visualizar sua conta e realizar pagamentos, este sistema utiliza um sistema externo de envio de e-mails ao cliente e as operações bancárias, como a realização de pagamentos e obter os dados da conta são viabilizadas pelo mainframe já existente do banco.
Nível 2: Container
A camada container expõe a arquitetura de forma simplificada, exibindo as tecnologias usadas e como a comunicação acontece. Mas atenção, neste cenário container não tem o mesmo significado de Docker, aqui container representa algo no qual um código possa ser executado ou algum dado ser armazenado, como por exemplo um aplicativo móvel, um servidor web back-end, um aplicativo web front-end, um banco de dados, um sistema de armazenamento de arquivos etc.
O diagrama de container contém um nível maior de detalhes e é útil para a(s) equipe(s) de desenvolvimento, arquitetos e devOps.
Pela imagem é possível obter mais detalhes sobre o sistema bancário, qual banco de dados é utilizado, como é realizada as comunicações com os sistemas externos, de que forma o usuário interage com o software e uma breve descrição da responsabilidade de cada item.
Nível 3: Componentes
O nível 3 exibe o conteúdo de um container com foco nas funcionalidades, apresentando suas responsabilidades e detalhes de tecnologia. Neste contexto, componente é uma funcionalidade de sistema encapsulada visto como uma unidade implementável, confira o exemplo abaixo.
Entenda que neste nível um componente pode ser um conjunto de classes, supondo que o sistema foi desenvolvido em POO (porém com a mesma responsabilidade, mesmo objetivo) ou um conjunto de módulos, quando o paradigma for funcional.
Nível 4: Código
O quarto e último nível do modelo é opcional e recomendado para componentes complexos e/ou importantes. O objetivo é apresentar de forma simples como um componente deve ser implementado, para isso é possível usar diagramas de classe UML, diagrama de entidade e relacionamento, etc. Note no exemplo abaixo que o diagrama do componente Mainframe Banking System Facade exibe apenas os nomes das classes e seus relacionamentos.
Um mapa pode ser feito de várias formas, mas independente do estilo, sua diagramação é similar e a leitura se torna fácil devido a familiaridade. O C4 tem o mesmo conceito, por isso pode ser apresentado para diferentes públicos, com o mesmo modelo é possível focar nos diagramas mais genéricos com a área de negócio e apresentar as camadas mais específicas apenas para o time técnico.
Qualquer notação pode ser usada para criar os diagramas, o modelo não prescreve uma em particular, porém a ideia principal é que os diagramas sejam autônomos, para que possam ser entendidos por todos sem uma narrativa complementar. Para isso é preciso que os diagramas possuam títulos, legendas para todos os itens (formas, cores, linhas etc) e os acrônimos e abreviações devem ser compreensíveis a todos ou fazer parte da legenda. Os elementos dos diagramas devem conter uma descrição com as principais responsabilidades, os containers e componentes incluir a sua tecnologia e todos os relacionamentos devem ser unidirecionais, contendo um rótulo específico, e para relacionamento entre containers é preciso ter a tecnologia de comunicação descrita.
Mas lembre-se, este modelo é apenas uma ferramenta, todos os problemas apresentados com relação a documentação e o que a falta dela pode trazer não serão resolvidos com o uso do C4, ainda depende de como a ferramenta será usada.
Referência:
