O que você sabe sobre desenvolvimento orientado a documentos?

Por que precisamos de algum documento no processo de desenvolvimento?

E essa afirmação de que o código se documenta ?

Vamos considerar o cenário mais comum: o código do sistema (seja um programa, projeto ou produto) está sendo escrito durante um longo período, e a equipe muda gradativamente durante esse processo, levando consigo certos conhecimentos sobre o sistema à medida que os desenvolvedores vão embora.

O que podemos fazer nesse caso?

A resposta mais simples é escrever uma especificação que capture todos os detalhes de implementação para garantir que o sistema atenda aos requisitos originais.

Porém, tal documento é muito difícil de redigir com antecedência e, durante o processo de desenvolvimento, alguns detalhes de implementação podem mudar (adaptação ao mercado/novas solicitações de mecânica, etc.). Então, o que podemos conceber para melhorar o fator ônibus ?

Vamos tentar seguir um fluxo que pode ser uma das possíveis soluções para resolver o problema mencionado acima.

Requisitos e RFC

Primeiro, precisamos descrever o design inicial com base nos requisitos das partes interessadas e documentá-lo. Depois disso, este documento pode ser compartilhado com outras equipes e seu feedback solicitado: pedir para implementar determinados recursos, comentar o design inicial, corrigir uma determinada interface, etc. Tal documento pode ser chamado de RFC .

RFC , ou "Solicitação de comentários", é um documento distribuído entre as partes interessadas — incluindo desenvolvedores, arquitetos e outras equipes — para coletar feedback, comentários e sugestões. É menos detalhado que uma especificação e inclui apenas o problema inicial, a tarefa e o domínio da solução. Sendo mais flexível, permite aceitar ativamente alterações no design, garantindo uma compreensão profunda da tarefa e facilitando a qualidade e a tomada de decisões ponderadas.

Compromisso de Design e ADR

Ok, definimos os requisitos técnicos e reunimos os requisitos de outras equipes . Qual é o próximo?

Nesta fase é necessário finalizar o desenho do sistema e todas as principais funções que este irá desempenhar. Para este propósito, escrevemos um ADR .

ADR , ou "Registro de Decisão de Arquitetura", é um documento que registra importantes decisões de arquitetura tomadas durante o processo de desenvolvimento de software. Cada ADR descreve uma decisão arquitetônica específica de alto nível, seu contexto, alternativas consideradas, a decisão tomada e a motivação para escolher esses detalhes específicos em detrimento de outros.

Tal documento permite que cada membro da equipe (e também outras equipes) compreenda os princípios e valores que sustentam o design. Se um novo desenvolvedor se juntar à equipe anos depois e perguntar: “Por que você fez isso dessa maneira?”, ele poderá ver este documento, que responderá a todas as suas perguntas.

Especificação

Agora é hora de escrever o código e suas especificações. Nesta fase, trabalhamos minuciosamente cada funcionalidade, compilando simultaneamente todas as informações e detalhes de implementação num documento especial. Este documento deve refletir os atuais requisitos de baixo nível do sistema.

Um ponto importante : durante o ciclo de vida do software, tal especificação pode mudar significativamente, e tudo bem. No entanto, é muito importante permanecer dentro do design e da arquitetura originais para evitar que a base de código se torne algo incontrolável.

Plano de teste

Por que é necessário? É fundamental que um plano de teste seja construído não com base em código que foi escrito de acordo com a especificação (escrevemos código e testes para esse código para que eles passem), mas com base em um design que inclua cenários críticos que devem ser processados corretamente . Também é muito conveniente que você possa enviar tal plano de testes para revisão para outras equipes (para integrações ou apenas para testes adicionais), deixando claro como o sistema se comportará em diferentes situações.

O que inclui?

• Todos os cenários possíveis de operação do sistema

  • Caminho feliz
  • Caminho triste
  • Manipulação de erros

• Todas as invariantes possíveis que devem ser mantidas durante a operação do sistema

• Testes de aceitação para verificar o estado do sistema no início (devem considerar o ambiente, por exemplo, dados na rede)

  
  

Finalizamos o design , escrevemos o código e as especificações e compilamos o plano de teste . Já parece bastante sólido! Mas o que mais poderíamos acrescentar?

Plano de preparação

Tal plano pode ser necessário até certo ponto para melhorar o fator barramento e criar condições nas quais qualquer membro da equipe possa implantar o sistema e verificar seu estado.

Por que não podemos viver sem isso? Podemos, mas no mundo real, grandes equipes onde muitas pessoas são responsáveis por diferentes partes do sistema, e o processo de implantação pode ser totalmente delegado ao DevOps. O que há de errado nisso, já que escrevemos testes, os colocamos em CI e verificamos vulnerabilidades, precisamos de mais alguma coisa? Talvez não, mas muitas vezes os testes não consideram o estado atual do sistema e testam não exatamente o que gostaríamos.

Qual plano de implantação pode conter :

• Uma descrição completa das ações que precisam ser executadas para que a implantação ocorra
• Parâmetros de implantação:
  • Variáveis ambientais
  • Estado inicial
  • Parâmetros para lançamento
• Um plano para caso algo dê errado em qualquer etapa
• Um plano de backup, se possível
• O estado necessário ao qual o sistema deve ser levado caso a continuação da implantação não seja possível
• Ações que precisam ser executadas após a implantação
  • Notificar outras equipes
  • Habilite as integrações necessárias, se necessário

Nada complicado, certo? Ter esse documento para uma atualização específica pode melhorar significativamente o fator barramento e evitar a dependência de indivíduos específicos. Não é isso que queremos?

Conclusão

No processo de desenvolvimento de software, é importante não apenas escrever código, mas também criar documentação que garanta compreensão e consistência em todas as etapas do desenvolvimento. A documentação pode ser o próprio código , mas a experiência tem mostrado que a documentação é muito importante para manter a qualidade, estabilidade e escalabilidade futura do sistema, principalmente quando a equipe muda durante o desenvolvimento, e também quando o projeto evolui e se adapta a novos requisitos.

A documentação inclui RFC (solicitação de comentários), ADR (registros de arquitetura), especificação , planos de teste , planos de implantação e muito mais. Isto irá garantir a retenção do conhecimento na equipa , simplificar o processo de integração de novos colaboradores no projeto e aumentar a fiabilidade global e a resistência do sistema às mudanças .