Um diário para suas aplicações

Um problema frequente na manutenção de sistemas legados é entender por que as coisas estão como estão. É preciso incorporar o pensamento dos desenvolvedores da época, entender o contexto do desenvolvimento, o conhecimento de seus criadores e o cenário político da organização responsável. Isso dificulta o trabalho do desenvolvedor/arquiteto em manter um padrão e realizar manutenções no sistema de forma clara, coesa e sustentável.

Em minha visão pessoal, quando fazemos algo, aquilo deve ter um sentido objetivo do por que está sendo feito. Esse sentido pode ser lógico, um passo de fé, religioso, sentimental ou um desejo, MAS DEVE HAVER UM MOTIVO. Quando fazemos as coisas sem um sentido claro, estamos tomando decisões ao acaso, que nos levam para um caminho desconhecido e mal planejado. Permitimos que a "aleatoriedade" tome nossas decisões, fazendo-nos perder o controle de nossas vidas.

Se aplicarmos o conceito de "existir um sentido" no desenvolvimento de software, podemos extrair a ideia de que em um sistema ideal cada decisão tomada ao longo de seu ciclo de vida deve ter uma razão clara, desde sua concepção até sua manutenção contínua. As decisões tomadas devem direcionar a solução para um cenário planejado, baseado em requisitos claros e controlado por boas práticas de engenharia de software, onde cada micro decisão constrói um movimento que leva o sistema ao seu estado atual. Nesse estado, espera-se que contenha características como manutenibilidade, clareza, intuitividade e regras bem definidas, com detalhes adiados o máximo possível para facilitar eventuais mudanças.

Certo, confesso que isso é muita filosofia para uma simples sugestão de ideia, mas como este mesmo texto já diz: as coisas devem ter um sentido para existirem. Vamos, então, caminhar para a solução.

Se cada passo no ciclo de vida de um software é importante para entender seu direcionamento, como um desenvolvedor/arquiteto recém-chegado em uma organização, sem contato com seus criadores e mantenedores, poderia compreender essas pequenas decisões tomadas ao longo do tempo sem depender de dedução? A resposta é óbvia: a documentação. Ok, fácil. Mas como essa documentação deveria ser?

Por que não uma documentação burocrática e técnica?

As documentações comuns são normalmente cercadas de requisitos que as fazem ter um propósito bastante diferente do nosso objetivo.

1. Uma documentação constantemente atualizada

Em uma documentação técnica padrão, sua constante atualização e evolução são necessárias, pois ela acompanha o sistema, que acompanha o modelo de negócio, que muda constantemente. Mas será que a documentação que procuramos precisa ser assim?

Se o que buscamos é traçar uma linha cronológica que nos permita registrar as decisões tomadas e seus porquês, não faz sentido exigir que essa lista seja atualizada, pois as decisões tomadas no passado não podem ser alteradas, apenas corrigidas no presente. Então, precisamos de uma documentação que não altere as informações registradas no passado. Check!

2. Uma documentação com conceitos corretos

Se lemos uma documentação técnica, esperamos que seus registros estejam condizentes com os conceitos apresentados e com suas sintaxes corretas. Mas será que isso importa para o nosso objetivo?

Uma documentação que registre as tomadas de decisão de um sistema não precisa estar necessariamente correta. Eu sei, parece estranho, mas vamos dissertar sobre isso.

Se durante o desenvolvimento de um sistema legado, os responsáveis da época tomaram uma decisão errada por conta de uma falha em seus conhecimentos ou imaturidade técnica, isso não pode ser corrigido na documentação, pois impactaria na análise macro que nos permite entender a atual situação do sistema, "se queremos entender como uma pessoa age, devemos pensar como ela pensa".

Tudo bem, então já podemos considerar que nossa documentação ideal não pode ser atualizada por conta de informações incorretas, mas ainda faz sentido criar um campo para as erratas, que registre as informações incorretas consideradas juntamente com a argumentação do por que elas estão incorretas.

3. Uma documentação que exija pré-requisitos

Uma documentação padrão normalmente exige que seus leitores busquem uma base para que algumas abstrações fiquem claras durante seu estudo. Vamos exemplificar: a documentação da framework React exige um pré-requisito de entender a linguagem de programação JavaScript ou TypeScript, pois utiliza ambas para seu desenvolvimento. Mas na nossa documentação ideal, deveria haver pré-requisitos?

Se a ideia principal é apenas permitir que o leitor "pense como o desenvolvedor pensou", não faz sentido que ela esteja em uma linguagem técnica que exija do leitor um conhecimento mais aprofundado sobre algum tema, pois nesse caso, estaria mudando sua proposta de ser apenas um registro das decisões tomadas para se tornar um manual técnico de ferramentas e técnicas.

Incrível! Então nossa documentação ideal deve evitar ser técnica e priorizar apenas a argumentação do porquê de se fazer algo de determinada forma.

Uma analogia ao mundo real

Vamos imaginar que escrevemos um diário. Esse diário tem o objetivo de registrar nossas vidas, pensamentos e acontecimentos. Não apagamos histórias já registradas pois queremos guardar a recordação. Frequentemente anotamos coisas que julgamos "não tão expressivas", mas com o tempo, percebemos que são informações valiosas. Quando anotamos algo, não esperamos precisar lembrar de contextos externos ao reler no futuro - escrevemos os contextos para facilitar nossa compreensão posterior. A escrita em um diário normalmente tem um efeito "terapêutico" em nossas mentes, pois nos faz refletir sobre quem somos e por que agimos.

A realidade é que o diário é algo natural, que flui de maneira suave e não deve ser visto como uma obrigação, mas sim como uma forma de agrupar pensamentos, acontecimentos e decisões da nossa vida para que possamos refletir, relembrar e evitar os mesmos erros do passado. Da mesma forma gostaríamos que nossa documentação fosse.

Como então essa "documentação" deveria ser?

Levantamos uma série de requisitos de uma documentação técnica padrão para compará-los com nossa necessidade no modelo proposto e, através deles, entendemos que precisaríamos fazer algumas alterações. Mas quais?

1. Os registros devem ser readonly: a documentação deve ser apenas escrita e não alterada, permitindo registrar os acontecimentos com seus contextos e pensamentos, com uma breve explicação do porquê daquilo ter sido feito como foi, mas jamais deverá ser alterada.
2. Deve existir uma errata: a documentação deve permitir que os erros técnicos sejam destacados com suas respectivas explicações, para que ninguém interprete algo errado como certo nem certo como errado.
3. Não deve exigir conhecimento técnico prévio: a documentação não deve exigir conhecimento técnico como pré-requisito para que o leitor entenda seu conteúdo, pois perderia sua proposta de ser um livro de registros e se tornaria uma documentação técnica.
4. Sua escrita deve ser algo natural que provoque o pensamento crítico: a escrita da documentação não deve ser um fardo, deve ser apenas o registro do pensamento, contexto e motivo pelo qual ações foram feitas durante o desenvolvimento e evolução de um sistema.

Um modelo descoberto

Conseguimos! criamos um modelo ideal para registrarmos as decisões tomadas em nossas aplicações, que seja leve, intuitivo e útil. Mas, como seria esse modelo na prática?

Decisão

• Título: Utilização de uma biblioteca centralizada para utilizar recursos comuns a todas as aplicações
• Data da Decisão: 05/01/2025
• Tipo de Decisão: Arquitetural
• Descrição:
  • Contexto: Várias APIs precisariam ser criadas em um intervalo curto e muitas das vezes com seus desenvolvimentos em paralelo. E todas elas teriam recursos em comum que poderiam ser reaproveitáveis
  • Motivação: Seria necessário reutilizar várias soluções para todos os projetos.
  • Detalhamento: Foi decidido centralizar uma biblioteca com funcionalidades reaproveitáveis que não estejam vinculadas a regras de negócio para ser utilizadas por todas as novas APIs criadas, onde as mesmas serão constantemente atualizadas (existirá um processo rotineiro para atualizar essa biblioteca em todos os sistemas). Dentre suas funcionalidades, será incluído o adaptador que permite a comunicação das APIs HTTP com os sistemas legados em WCF.
• Responsáveis: João das Couves, Jhali Rheinviei, Tsujiro Kisidane

Errata

• Decisão Original: Utilização de uma biblioteca centralizada para utilizar recursos comuns a todas as aplicações
• Data da Errata: 10/02/2025
• Descrição do Erro: Durante o desenvolvimento, entendemos que seria muito custoso manter a referência dos serviços WCF dentro do adaptador do legado, pois a cada atualização do serviço, seria necessário subir uma nova versão da biblioteca.
• Correção e Motivo: Foi decidido separar a referência dos serviços WCF legados do adaptador dentro da biblioteca, passando a referência agora para cada aplicação que fará sua própria gestão.
• Responsáveis pela Errata: Tsujiro Kisidane

Acho que é isso…

Bom, enfim, acho que atingimos o objetivo proposto no início do artigo, certo? talvez você ache a ideia incrível, talvez você ache incrivelmente patética. Talvez você conheça essa ideia de um verdadeiro autor ou outra pessoa que já tenha registrado essa ideia.

A verdade é que isso é apenas um compartilhamento de uma ideia que tive quando refletia sobre as dificuldades de se dar manutenção em um sistema onde você precise se aprofundar em porque ele é do jeito que é para que possa entender seu objetivo, não parei para pesquisar se já existe um conteúdo assim, ou se algum autor já propôs essa ideia. Apenas pensei, escrevi e postei 👍

Enfim, espero que esse conteúdo duvidoso tenha acrescido algo na sua vida miserável. Até logo, meus amigos.