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 é que capture todos os detalhes de implementação para garantir que o sistema atenda aos requisitos originais. escrever uma especificação 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 , 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. RFC Compromisso de Design e ADR Ok, e . Qual é o próximo? definimos os requisitos técnicos reunimos os requisitos de outras equipes Nesta fase é necessário e todas as principais funções que este irá desempenhar. Para este propósito, escrevemos um . finalizar o desenho do sistema 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 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. ADR ADR Tal documento permite que cada membro da equipe (e também outras equipes) 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. compreenda 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. : 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. Um ponto importante Plano de teste Por que é necessário? É fundamental que um plano de teste seja construído que foi escrito de acordo com a especificação (escrevemos código e testes para esse código para que eles passem), mas com que inclua cenários críticos que . 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. não com base em código base em um design devem ser processados corretamente 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 , escrevemos o código e e compilamos o . Já parece bastante sólido! Mas o que mais poderíamos acrescentar? design as especificações plano de teste Plano de preparação Tal plano pode ser necessário até certo ponto para e criar condições nas quais qualquer membro da equipe possa implantar o sistema e verificar seu estado. melhorar o fator barramento 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 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. totalmente delegado 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 e de indivíduos específicos. Não é isso que queremos? melhorar significativamente o fator barramento evitar a dependência 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 , 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. pode ser o próprio código A documentação inclui (solicitação de comentários), (registros de arquitetura), , , e muito mais. Isto irá garantir a , simplificar o processo de no projeto e . RFC ADR especificação planos de teste planos de implantação retenção do conhecimento na equipa integração de novos colaboradores aumentar a fiabilidade global e a resistência do sistema às mudanças
