Por que utilizar bons modelos (diagramas) é importante para arquitetura de software?

Software em funcionamento é mais relevante que documentação abrangente. Concordo com esse princípio expresso no manifesto ágil. Entretanto, acho que ele foi interpretado e utilizado de forma infeliz, como justificativa, por tempo demais, para decisões arbitrárias que levaram a um incremento no custo de desenvolvimento e manutenção de software.

Documentação abrangente é fundamental para redução do custo de manutenção de um software e, no longo prazo, é fundamental para sua evolução tecnológica.

Por que o código não é suficiente?

Há quem defenda que a máxima expressão da verdade, em um software, está em seu código. Não concordo com isso. Entendo que [tweet]nenhum software pode ser analisado coerentemente sem levar em conta o contexto de seu desenvolvimento (como e por quem é feito) e sua finalidade em produção (o problema que ajuda a resolver).[/tweet]

Nem sempre o código reflete as motivações de seu desenvolvimento. Aliás, com frequência, o código aponta em direção oposta (o que é, por si só, uma enorme dívida técnica).

Ao longo do tempo as motivações mudam e o código também. Infelizmente, com muita frequência, pressões e crenças (das quais, em sua maioria, não compactuo), associadas a um processo desregrado, levam a uma “erosão conceitual” – dívidas técnicas se acumulam e a expressividade é comprometida.

Mesmo quando o código expressa, de forma clara e objetiva, as motivações de seu desenvolvimento, em sistemas grandes, ele acaba sendo complexo demais para a maior parte das discussões, sobretudo as que envolvem os especialistas de domínio.

Por que os testes não são suficientes?

Há também quem defenda que o conjunto de testes, bem escrito e com bom índice de cobertura, é recurso suficiente para o entendimento de um software. Mais uma vez, não concordo.

Os testes simplificam o entendimento de um software, sem dúvidas. Entretanto, em sistemas grandes, serão tão numerosos e tão diversos que não serão úteis para um primeiro entendimento.

Os testes tem utilidade de compreensão para a atividade operacional de escrita do código, mas não são tão relevantes para o atingimento das metas do processo de desenvolvimento em sentido mais amplo, sobretudo na composição da organização incluindo o negócio.

Por que diagramas são necessários?

Quando estamos lidando com sistemas complexos, é útil fazer análises em diferentes níveis de abstração. O código e os testes são, em última instância, as fontes com menor abstração disponível para entender o software.

Bons modelos permitem a interpretação do software em níveis mais altos de abstração, facilitando a comunicação e o envolvimento das diversas partes interessadas. Além disso, também ajudam a explicar, para quem não está envolvido no processo de desenvolvimento desde o início, o(s) problema(s) que está se tentando resolver e a solução que se está implementando.

O desenvolvimento de modelos (diagramas) que ajudem a entender o software e o domínio, em mais de um nível de abstração, faz parte dos processos de desenvolvimento e manutenção do software. Em minha interpretação, negligenciar este fato é assumir uma dívida técnica cara demais.

Como lidar com diagramas desatualizados?

Em termos simples, com processos maduros que impedem que a desatualização aconteça.

Infelizmente, diagramas e comentários desatualizados não são submetidos a um compilador e não geram falhas de build. Há diversas iniciativas que visam gerar documentações atualizadas, a partir do código. Entretanto, acredito que ainda estamos distantes do dia em que essas soluções irão funcionar de forma ideal.

A minha defesa é de que o processo profissional de desenvolvimento de software deva contemplar sempre a atualização da documentação. Entendo que isso somente é possível se essa atualização for parte fundamental para a aplicação de modificações do código.

Aliás, entendo que seja responsabilidade e interesse do time manter o software fácil de explicar. Se esse não for o caso, com o tempo, o custo de manutenção irá invariavelmente aumentar.

Os diagramas e modelos deveriam ser o “primeiro alvo” para análise do software e para a implementação da modificação. Em seguida, os testes e a base de código.

Não tenho diagramas para explicar meu software. E agora?

Sou avesso a complexidade e entendo que o primeiro passo para atacar a complexidade é permitir discussões em diferentes níveis de abstração.

O primeiro passo para atacar uma realidade complexa é a construção de modelos simplificadores.

Se seu time não mantem diagramas para explicitar diferentes níveis de abstração da sua solução, entendo que tenha uma enorme dívida técnica que irá se revelar em grande dificuldade, sobretudo de manutenção e evolução tecnológica. PAGUE ESSA DÍVIDA!

Não tenho “competência” para elaborar diagramas. O que fazer?

Entendo que os skills necessários para elaborar e manter uma boa documentação não sejam comuns a todos os desenvolvedores. Nem acho que essa seria uma pré-condição.

A manutenção de diagramas, entretanto, é skill fundamental para o arquiteto de software.

Já disse, mais de uma vez, que não entendo que o arquiteto de software seja, necessariamente, um developer senior-senior. Embora concorde que a maioria dos bons arquitetos que conheço o sejam.

O arquiteto de software, como orquestrador, tem a responsabildiade e atribuição de garantir que o sistema tenha diagramas atualizados e efetivos.

Na prática…

Se seu software não tem documentação abrangente (abstrações, em diversos níveis, que explicam o software), você tem uma dívida técnica. Pague-a!

Embora exista a possibilidade do “time” manter a documentação, é potencialmente mais barato concentrar essa responsabilidade e desenvolver essa competência em alguns membros, geralmente com outras atribuições de arquitetura.

O processo de desenvolvimento será mais efetivo se considerar o processo de análise e desenvolvimento de soluções, começando pela documentação e em seguida no código.

Vamos continuar essa conversa?

Sempre digo que “são as cicatrizes que contam a história do guerreiro”. Compartilhei aqui algumas de minhas cicatrizes. Adoraria saber um pouco das suas.  Se possível, compartilhe um pouco da realidade em sua empresa…

Compartilhe este insight:

6 respostas

  1. Concordo e Padeço do mesmo Dilema. Nunca fomos bons em criar documentação, tampouco, mantê-la atualizada. Sempre foi uma atividade considerada custosa e chata; desprezada pelos melhores entendedores da solução e, na maioria das vezes, delegada aos novatos ou profissionais menos qualificados.

    Frameworks e Ferramentas automação? Alguns caros, complexos e ineficiêntes : ineficazes.

    Não eh à toa que achamos uma boa desculpa para não fazê-la mais: “com Ágil não precisamos de documentação”. Uma interpretação leviana e tendenciosamente preguiça dos modelos Ágeis.

    Na minha opinião: nem tanto ao céu, nem tanto à terra. Precisamos nos mobilizar para achar um meio termo. Algo que seja suficientemente simples, acessível, dinâmico e, principalmente, didático.

    A Documentação do Sistema tem sua importância, SIM. Precisa ser um instrumento de aceleração e excelência nas tomadas de decisão e transferência de conhecimento.

    Tô aberto a sugestões, também.
    (O calo aperta)

  2. Preciso pagar essa dívida! Saberia me recomendar templates/frameworks/abordagens para que eu possa iniciar o pagamento da minha dívida?

    1. Acredito que antes de buscar um conjunto ferramental que te dê apoio, é essencial iniciar o pagamento desta dívida pela sua última recomendação “Abordagens”, em um contexto mais abstrato, mais especificamente na busca por conteúdos e conceitos sobre planejamento, design, diagramação, padrões, criação de modelos …. que precisam estar bem esclarecidos antes de iniciar o pagamento da dívida. Quando estes conceitos estiverem bem claros, sobre criação de modelos, diagramação e documentação, ai sim podes buscar atalhos (frameworks, templates, abordagens). Caso a dívida já exista, pare o que está fazendo e pague-a (se é que isso é possível).

  3. Ótimo artigo!
    Mais uma vez, parabéns!
    Algum projeto de código aberto que você julga ser um exemplo a ser seguido?

  4. Olá Elemar, Seus artigos são fantásticos, obrigado por dedicar tempo e esforço para disseminar conteúdos de qualidade.

    Só uma dúvida essa dívida técnica seria o “technical debt” ?

    Obs:. Pelo que foi descrito acredito se tratar do technical debt. Não seria o caso de colocar o termo em Inglês para facilitar o entendimento, e colocar uma nota de rodapé caso alguém não conheça o termo.

    Mais uma vez parabéns e obrigado.

  5. Pra mim, sempre soou estranho software ter zero documentação. O próprio código ser o único documento, não é tão eficaz quando se quer uma resposta rápida do funcionamento básico. Usando por exemplo, um diagrama de fluxo de estado, é muito mais rápido o entendimento e ideal para se debater ideias e melhorias com o PO, Stackholder, etc…

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Elemar Júnior

Sou fundador e CEO da EximiaCo e atuo como tech trusted advisor ajudando diversas empresas a gerar mais resultados através da tecnologia.

Elemar Júnior

Sou fundador e CEO da EximiaCo e atuo como tech trusted advisor ajudando diversas empresas a gerar mais resultados através da tecnologia.

Mais insights para o seu negócio

Veja mais alguns estudos e reflexões que podem gerar alguns insights para o seu negócio:

Reduction operations are those that reduce a collection of values to a single value. In this post, I will share...
No post anterior, eu mencionei uma série de post do Mario Fusco questionando a forma como desenvolvedores Java estão implementando os design...
Nunca trabalhei em um circo, tampouco criei elefantes! Portanto, advirto que os “fatos” que lerá aqui foram relatados por amigos,...
RavenDB utiliza Lucene como motor de indexação. Isso significa suporte natural a full-text search que pode ser facilmente habilitado a partir da...
Neste post, compartilho mais algumas ideias que tenho adotado, com êxito, em meus projetos envolvendo Microsserviços e que podem ajudar...
Microsserviços podem se transformar, rapidamente, em um pesadelo para a área de operações. Diferente do que ocorre com um monolítico,...
× Precisa de ajuda?