Uma prática pouco aproveitada no desenvolvimento de software é a de usar desenhos técnicos para facilitar a elaboração de soluções, validação de ideias e nivelamento de conhecimento. O tema apresenta formas para auxiliar a criação de desenhos técnicos e como eles podem contribuir para o desenvolvimento de softwares melhores.

O desenho técnico no desenvolvimento de software está atrelado ao tema Documentação Técnica, isso porque desenhar é uma forma de documentar, mas pode ir além contribuindo para elaboração e definição de como softwares são construídos.

Em áreas como engenharia mecânica, elétrica, civil, dentre outras, os desenhos técnicos normalmente são artefatos produzidos e utilizados antes da ação de implementação. Na engenharia de software a prática geralmente é a inversa, primeiro implementa-se o código e depois quando necessário gera-se um desenho.

Enquanto em outras áreas o resultado final é visível, em software ele pode ser camuflado pelo fato do software não ser algo material e seus problemas muitas vezes imperceptíveis. Em software pode-se perceber “a confusão” existente no código e na arquitetura somente em casos como na geração de diagramas através de engenharia reversa, exemplificada abaixo.

A prática já citada e usada nas demais engenharias que pode ser útil para evitar situações semelhantes ao desenho anterior, é: Desenhar antes de implementar!

O tema apresenta na sequência como desenvolvedores(as) podem trabalhar para incorporar desenhos técnicos no dia a dia de forma que sejam úteis e gerem valor aos times.

A técnica de desenhar

Em engenharia de software, desenhos geralmente remetem a diagramas, que remetem a uso de notações como UML, ArchiMate, SysML. Notações que por vários motivos atualmente são descartadas em muitos times de desenvolvimento. Porém a arte de desenhar não está amarrada a notações ou outras regras.

Desenhar é representar de forma visual algo que está no nível da imaginação!

Muitas vezes o que está sendo pensado e idealizado por uma pessoa, pode não estar sendo visualizado da mesma forma pelas demais, por este motivo desenhar se torna tão importante, pois contribui para que todos tenham o mesmo entendimento.

A atividade de desenhar, geralmente divertida na infância, é algo que muitos não se identificam na fase adulta, o que contribui para que seja deixada de lado. Porém para a maioria dos desenhos utilizados na área profissional há técnicas que auxiliam a desenhar.

Um exercício rápido, pense em um avião!

Há grandes chances de o avião que você pensou ser o diferente do autor deste texto e de vários outros leitores deste tema.

Para que todos tenham o mesmo entendimento, vamos então desenhar um avião.

O desenho não parece muito bom, mas já dá condições de todos visualizarem o mesmo tipo de avião, que parece ser à jato, os utilizados em voos comerciais. Mas esse desenho pode ser melhorado! Entra então a técnica para desenhar, acompanhe a figura abaixo:

Houve grandes melhorias! E para isso não foi necessário talento, mas sim apenas técnica (embora talento ajude muito!).

Ainda assim, caso a intenção for construir um avião, duas coisas parecem claras:

• Não construiríamos um avião sem desenhar primeiro.
• O desenho anterior não seria o adequado para um time construir tal avião.

Seria necessário um desenho técnico, com detalhamento útil, algo como:

O desenho acima seria provavelmente mais adequado. Mas isso não tira o valor dos desenhos iniciais, eles são parte do processo de entendimento e detalhamento do que precisa ser implementado.

Em qualquer solução de software a ser implementada, pode-se atuar com níveis de desenho adequados para cada momento. Podendo ser eles:

• Rabiscar a ideia, possibilitando um entendimento igual a todos sobre a solução.
• Evoluir o desenho, melhorando a composição para que times técnicos visualizem a solução.
• Detalhar o desenho usando boas práticas e especificações que facilitem ao times técnicos implementar o código.

Nestes momentos, antes de iniciar implementações, é que times poderão pensar mais sobre a solução planejada, validando a complexidade, o impacto e ponderando como irão implementar, antes de usar o tempo para codificar.

Diagramas

A palavra diagrama, no contexto de desenho técnico geralmente possui uma carga negativa, isso porque desenvolvedores(as) associam tal palavra aos diversos diagramas da notação UML, como o mostrado na figura inicial. No livro “Princípios, Padrões e Práticas Ágeis em C#”, escrito por Robert C. Martin, é abordado (cap. 14, Trabalhando com Diagramas) na visão do autor e com justificativas, como desenvolvedores(as) podem desperdiçar seu tempo ao criarem diagramas grandes, complexos e sem utilidade.

Diagramas são um aliado para área de software, pois permitem uma representação visual estruturada e simplificada de um conceito ou ideia, mesmo sendo às vezes apenas um conjunto de “caixas e linhas”.

Diagramar uma ideia não precisa ser uma tarefa morosa e complexa, mas pode ser um pouco mais do que apenas rabiscar “caixas e linhas”. Um bom diagrama precisa:

• Forçar o time à entender o motivo de cada item presente, de cada relação criada, de cada decisão tomada.
• Comunicar de forma clara sem espaço para múltiplas interpretações.
• Respeitar um escopo proposto, para não se tornar grande ou complexo demais.
• Conter informações que sofram poucas modificações para não ficar desatualizado rapidamente.
• Usar uma notação simples.
• Ser de fácil manutenção.

Notações

Uma notação em engenharia de software determina a forma com a qual os elementos devem ser desenhados ou descritos. Isso inclui formas geométricas, tipos de linhas, informações auxiliares, dentre outros. Notações já citadas como a UML, ArchiMate, SysML, atualmente talvez sejam descartadas, dentre muitos motivos, por ter notações robustas que se tornam de certo modo complexas.

Para a área de engenharia de software, uma notação simples (embora não se declare uma notação) é o modelo C4 Model. Criado por Simon Brown entre 2006 e 2011, que se inspirou nas raízes de UML mas buscando tornar mais simples e atrativa a tarefa de design de software, C4 se tornou popular a partir de 2018.

O C4 model foca em tornar mais livre a forma de diagramar, sugerindo boas práticas para que os diagramas tenham valor. Trazendo o conceito de “Maps of your code” para criar mapas do código com vários níveis de detalhes (semelhantes a aumentar ou diminuir o zoom em uma mapa do Google Maps) ele propõe o uso de diagramas dos quais o guia destaca:

• Contexto do sistema: Apresenta um ponto de partida para diagramar um software, focando na visão geral sem trazer detalhes técnicos. Recomendado para diálogo com pessoas não técnicas.
• Contêiner: Amplia sobre o diagrama anterior o escopo visualizado do software, mostrando os blocos com informações técnicas de alto nível.
• Componente: Amplia sobre o diagrama anterior a visão sobre um contêiner individual, mostrando os componentes dentro dele.

O guia recomenda o uso de C4 model e a leitura do conteúdo publicada no site oficial, onde são apresentados outros diagramas não citados aqui. Nos exemplos na sequência do tema, vários diagramas seguem a técnica C4 Model.

Público alvo

Um fator importante a ser considerado ao fazer desenhos técnicos é o público para qual se destina o desenho. Isso pode determinar a notação, termos e detalhes a serem utilizados.

Para facilitar o entendimento para quem vê o desenho, é recomendável quando necessário, o uso de diferentes níveis de desenho. Porém é importante estar atento às informações repetidas nestes desenhos, já que toda repetição de informação pode se tornar um ponto de desatualização caso um desenho seja modificado e outro não.

O público alvo deve, sempre que desejar, ter acesso para visualizar os desenhos. Isso pode ser feito através de meios físicos, como imprimir o desenho e colocar em local visível e público, ou meio virtual disponibilizando um link confiável que pode ser acessado quando necessário.

O que desenhar

É comum ao fazer desenhos técnicos haver uma confusão com relação ao que desenhar e como desenhar. Um exemplo disso são frases como:

• - Vou fazer um diagrama de componentes do sistema.
• - Vou fazer um diagrama de sequência do sistema.
• - Vou fazer um diagrama ER da base de dados.

Nelas estão indicadas o desejo de desenhar “o todo”, no caso representados pelo sistema, ou base de dados. Mas o que deseja-se representar de fato é uma ideia, e um sistema e a base de dados não são a ideia, mas sim existirão para viabilizar a ideia. Já diagramas de componentes, sequência, ou até desenho livre são formas para representar uma ideia, podendo inclusive um mesmo desenho conter várias destas formas.

Nessa linha é mais adequado pensar em frases como o exemplo abaixo:

Em um projeto fictício de nome Guia Hóspede, o qual está desenvolvendo uma solução para reservas de hotéis, houve a necessidade de que algumas ideias fossem melhor detalhadas para o time ter um entendimento igual sobre elas. Alguns integrantes do time propuseram:

• - Vou rabiscar minha ideia para solução de reservas de hotéis.
• - Vou desenhar o que o contexto de hotéis precisa ter para manter dados de acomodações.
• - Vou desenhar os passos que um cliente deverá fazer para reservar um hotel.
• - Vou desenhar os contextos e entidades para poder fazer reservas de hotéis.

Nelas estão melhor destacadas a ideia a qual o desenho precisa expressar, e aí está a importância de desenhos pois para detalhar tais ideias de forma textual geralmente criamos um conjunto de conteúdos que pode se tornar extenso e de difícil compreensão em uma “rápida olhada”.

Deve-se desenhar então toda ideia cuja representação visual irá facilitar entendimento e nivelar o conhecimento das pessoas.

Na prática, desenhar sempre deve ser uma atividade mais barata do que codificar e depois verificar que algo não foi bem pensado ou planejado.

Visão do negócio

O título do tema destaca o termo técnico, logo a visão de negócio pode parecer em um primeiro momento um item fora do escopo, porém desenhar a visão de negócio expressando algumas questões técnicas pode ser de grande importância na facilitação do entendimento e conversas entre os times de desenvolvimento e demais pessoas envolvidas em um projeto.

Um desenho relevante, que é apresentado pelo guia no pilar de negócio, é o modelo de domínio. Ele apresenta uma visão dos contextos, entidades e relacionamentos presentes na composição da ideia.

Além dele outros desenhos relacionados ao negócio podem ser utilizados:

• Visão de interação entre as Personas e papéis com os sistemas planejados ou existentes.
• Visão de relacionamento e dependência entre as soluções (produtos) e os sistemas os compõem.

Estes desenhos não precisam conter detalhes técnicos e sim os detalhes que indiquem a nível de negócio a relação entre cada item. A seguir um exemplo:

Seguindo o exemplo do projeto fictício Guia Hóspede, o time já tem definido questões como o modelo de negócio, personas e modelo de domínio. Agora junto ao time técnico foi iniciado o trabalho para detalhar a solução, abaixo o diagrama inicial:

Diagrama criado com a ferramenta diagrams.net (draw.io).

O diagrama parece simples, e esse é o objetivo, ele contém o básico para que pessoas de negócio e o time de desenvolvedores(as) entendam em alto nível o que é a solução.

Esse desenho pode ser utilizado em conversas do dia a dia, reuniões, onboarding de novos integrantes no time.

O diagrama usa o modelo de Contexto do sistema do C4 model, contendo:

• Título informativo sobre do que se trata o diagrama.
• Data de atualização do diagrama.
• Legenda sobre o que é cada item.
• As relações explicitando “quem depende/usa quem” e descrição.
• Link para materiais complementares, no caso o documento de Personas e o Modelo de domínios.

O time faz a impressão do diagrama atualizado de tempos em tempos e o coloca no hall de entrada para que todos possam visualizar essa informação. Também é publicada uma versão virtual do diagrama, para que o mesmo seja visualizado na sua última versão e para que outros conteúdos possam fazer links a esse material.

Um desenho simples, que pode gerar valor ao time.

Arquitetura da Solução

A arquitetura possibilita aos times uma grande oportunidade para utilização de desenhos técnicos. Conforme citado no tema Documentação Técnica, o conteúdo pode variar de acordo com a arquitetura escolhida ou já utilizada, desta forma os desenhos a serem criados e mantidos também podem variar.

O uso dos diagramas do C4 model são uma boa abordagem, e o guia sugere ainda algo mais simplificado usando a notação sugerida pelo C4 model. Nessa linha são duas as visões sugeridas:

• Arquitetura geral da solução.
• Arquitetura específico de um projeto com código fonte.

A seguir um detalhamento de cada visão.

☛ Diagrama com a arquitetura geral da solução

Pode ser equiparado ao diagrama de contexto ou paisagem do C4 model, mas podendo incluir na sua composição itens do diagrama de contêineres.

Seguindo o exemplo do Guia Hóspede, sendo uma arquitetura em microsserviços, o diagrama geral de arquitetura apresenta uma visão de todos os serviços existentes.

Diagrama criado com a ferramenta diagrams.net (draw.io).

Com este diagrama, sem a representação de atores, é possível:

• Compreender a dimensão da solução.
• Identificar que solução está organizada em duas camadas, sendo a superior com aplicações que focam no produto Guia Hóspede, e a inferior com serviços que focam nos domínios de negócio.
• Visualizar que a arquitetura é orientada a eventos, e trabalha com um API Gateway acima de todas API’s da camada de serviços.
• Ver nome, descrição e tecnologia utilizada em cada projeto.
• Ver a relação entre cada projeto, explicitando o sentido da dependência, a descrição breve da relação e o protocolo utilizado na comunicação.
• Verificar quais serviços possuem persistência de dados, quais publicam ou consomem mensagens e quais utilizam cache.
• Visualizar que na solução já está sendo construído o domínio para aluguéis de carros, mas este ainda está em início de desenvolvimento.
• Visualizar as dependências de sistemas externos.

A ferramenta utilizada na diagramação permite que seja criado links para outros conteúdos, que podem ser exibidos ou não na visualização do diagrama conforme figura abaixo:

Vários itens no diagrama possuem links para conteúdos complementares ou questões como:

• Código fonte do projeto, possibilitando navegar para o código de um projeto desejado.
• Documentação de API’s, possibilitando para aqueles que estejam entendo a solução verem também detalhes das API’s.
• Página de publicação da imagem docker do serviço, facilitando aos demais times o uso do artefato de deploy do serviço.
• Endereço de acesso a solução, para aplicações web.
• Página com a publicação do App, para aplicações mobile.
• Artefato publicado em ferramentas de gestão de bibliotecas.
• Página de acompanhamento ou administração de ferramentas.
• Documentações complementares.
• Dashboard de acompanhamento de releases e tarefas do projeto ou time responsável.

Estes links facilitam para desenvolvedores(as) navegarem entre projetos, documentações, dentre outros de forma mais rápida.

Diagramas desse nível podem se tornar grandes demais de acordo com o tamanho da solução. Nestes casos o ideal é procurar dividir o desenho, ou ter versões com menos detalhes. O C4 model recomenda um limite de 20 elementos, após isso o desenho pode se tornar confuso, porém isso pode variar de acordo com os itens presentes no diagrama e o uso do time.

☛ Diagrama com a arquitetura de um projeto específico.

Pode ser equiparado ao diagrama de contêiner do C4 model (nome que é conflitante com o conceito de contêineres depois da popularização do Docker), mas que segundo a documentação oficial refere-se a uma “unidade executável / implementável separadamente, ou que armazena dados”.

Na prática, é um diagrama que apresenta o escopo de um projeto com código fonte, e seguindo o conceito citado de “Maps of your code” trazido pelo C4 model, é um zoom sobre a “caixa do software” apresentada no diagrama de arquitetura geral. Desta forma, o diagrama anterior pode conter um link para o diagrama do projeto específico.

Pode-se nesse nível também fazer uso de diagramas equivalentes ao de componentes no C4 Model, mas focando nos componentes/classes bases do software.

Seguindo o exemplo do Guia Hóspede, no diagrama geral de arquitetura já é apresentada a composição do software, sendo assim o diagrama do projeto hotels-service foca em apresentar como está organizada a arquitetura lógica do código fonte.

Diagrama criado com a ferramenta diagrams.net (draw.io).

Com este diagrama é possível compreender:

• Como está organizado as camadas lógicas e o sentido de dependências entre elas.
• A interação com outros sistemas.
• As tecnologias, frameworks e bibliotecas principais utilizadas no código.

O tamanho e complexidade deste diagrama pode variar de acordo com o tipo e tamanho do projeto. Sua vantagem é que apresenta de forma simples e permite um rápido entendimento sobre como está organizado o projeto.

Possuir um diagrama de arquitetura mais geral e completo ou segregar essa informação em diagramas complementares é uma decisão dos times. Eles podem por exemplo optar por seguir rigorosamente o C4 model, embora o mesmo proponha seu uso como forma de orientação. Cada time pode adaptar suas necessidades.

Funcionalidades

Para funcionalidades deve-se ter atenção com relação a real necessidade e utilidade de desenhos. Isso porque uma funcionalidade pode ser algo com muitas variações e modificações ao longo do tempo, o que torna mais complexo expressar através de um desenho e mais difícil de manter atualizado.

Ainda assim há situações onde um desenho técnico contribui, e para isso pode-se recorrer ao uso de:

• Diagrama dinâmico: Um diagrama complementar do C4 model sugerido para histórias de usuário, caso de uso, etc.
• Diagrama de sequência: Um diagrama da notação UML que tem bastante valor para quando deseja-se representar uma sequência de processos e as mensagens trafegadas neles.
• Diagrama de atividade: Outro diagrama UML focado em representar fluxos de controle de uma atividade.

Seguindo o exemplo do Guia Hóspede, algumas funcionalidades principais possuem um diagrama dinâmico. O projeto hosting-sync-external-hotels-service possui uma rotina mais complexa com relação ao recebimento e atualização dos dados que os hotéis podem enviar. Segue o diagrama criado:

Diagrama criado com a ferramenta diagrams.net (draw.io).

Com este diagrama é possível compreender:

• Quais sistemas envolvidos no processo.
• A estratégia utilizada para fazer as atualizações de forma assíncrona.
• O fluxo de execução do sistema, facilitando entendimento sem necessidade de analisar o código fonte

Outro ponto importante é que ao criar o desenho antes de implementar o time teve condições de analisar e elaborar melhor a solução.

Manutenção e utilização

Manter e atualizar um desenho técnico é um grande desafio na engenharia de software, e não por falta de recursos técnicos, mas sim pela percepção de pouco valor de retorno dos desenhos e a falta de hábito de times de desenvolvimento para com o zelo sobre tais artefatos.

Normalmente times de desenvolvimento consideram que é mais barato implementar do que desenhar. Isso torna-se verdade quando é utilizada técnicas morosas ou cuja o foco do desenho esteja sobre coisas irrelevantes. Por este motivo é essencial que os times concordem sobre quais desenhos terão valor e serão úteis no dia a dia.

Como forma de estabelecer o hábito de desenhar e manter atualizados tais desenhos, o principal pensamento é o citado no início do tema:

Desenhar antes de implementar!

Esse pensamento não envolve apenas o ato de desenhar, mas sim de explicitar a ideia, planejar a solução e validar a mesma desenhando-a antes de implementar código.

Para criar tal hábito, é válido:

• Nas reuniões de planejamento das tarefas do time definir uma tarefa para que o time desenhe a solução antes de partir para a implementação.
• A cada implementação que modifique questões maiores no software, verificar se os desenhos existentes serão afetados e atualizá-los antes da modificação.
• Incluir no checklist de revisão do código um item referente a verificar se os desenhos foram atualizados caso necessário.

Outro aspecto que estimula os times à manterem atualizados os desenhos é perceberem que eles são utilizados. Nesse sentido deve-se buscar:

• Indicar a visualização do desenho sempre que as pessoas perguntarem sobre algo que nele esteja expressado.
• Usar os desenhos em reuniões e momentos de decisões onde eles possam colaborar para clareza das conversas.
• Dar espaço a todos para contribuírem nos desenhos, de forma que possam editá-los sempre que houver algo novo ou a ser corrigido.

Um bom desenho é um complemento de valor à documentação técnica e contribui para eficiência e escala de times de desenvolvimento.

Ferramentas

O conjunto de ferramentas disponíveis para desenhos técnicos é vasto, porém elas são secundárias, para iniciar com desenhos técnicos um bom quadro branco pode ser o suficiente (porém deve-se fotografar os desenhos!).

Mais do que indicar ferramentas específicas o guia cita abaixo recursos relevantes que podem ser verificados nas ferramentas escolhidas:

• Publicação de link para visualização do desenho. Útil para poder apresentar o desenho a outras pessoas.
• Versionamento, que pode ser junto a um repositório de código fonte ou soluções como GDrive, DropBox. É recomendável também que o arquivo a ser salvo siga um formato de texto plano, o que facilita comparação de versões.
• Paleta de componentes, sendo componentes neste caso, as formas geométricas usadas para compor o desenho.
• Exportação, em formatos como imagem e pdf.
• Links nos componentes do desenho, para que seja possível conectar documentações complementares. Esse recurso em versões impressas do desenho não faz sentido, mas normalmente os times usam a versão virtual .

Considerando os recursos citados, o guia sugere as ferramentas:

• Diagrams.net
• Lucid Chart
• Microsoft Visio
• PlantUML

No site oficial do C4 model na seção ferramentas, também há uma lista de ferramentas que dão suporte a C4 model e outros tipos de diagramas.

O site oficial do C4 model também oferece um checklist de validação de desenhos técnicos.