O que documentar antes de programar: lições de um CRM

O que documentar antes de programar depende do que vai custar caro se ficar sem decisão. Em quatro incrementos deste CRM de cobrança, as especificações cobriram bem as regras de cada funcionalidade e mesmo assim deixaram passar seis tipos de decisão, que viraram retrabalho, revisões e uma falha que existia desde o primeiro incremento sem ninguém ver. Nenhum deles era de um incremento só: todos cruzavam o sistema inteiro. Este artigo mostra cada lacuna com o que ela custou e a mudança de método que veio da retrospectiva, que contraria parte do que este blog defendia.

O que as especificações cobriam#

Cada incremento teve uma especificação aprovada antes do código, no formato descrito em Especificação de software: problema, regras com exemplos em valores, critérios de aceite verificáveis, premissas com a área que as validaria e decisões em aberto com dono. Cada critério virou um teste automatizado. O método seguia a recomendação de especificar o próximo incremento, e não o sistema inteiro, com um mapa curto do todo.

Funcionou para o que estava dentro de cada incremento. As regras de pagamento parcial, de estorno e de anulação de um contato foram decididas antes de existir código, várias delas com respostas que nenhuma opção previa. O que falhou foi o que ficava entre os incrementos.

Seis lacunas e o que cada uma custou#

Uma sétima, a de padrões de interface, já tem artigo próprio: o que faltou no design system.

Estados e transições#

O glossário do projeto define o que é um título “pago” e um título “retirado”. Nenhum documento mostrava como um título vai de um estado a outro. Três revisões da especificação de pagamentos foram, no fundo, a mesma pergunta em três formas.

1. O que faz um título pago voltar à cobrança? A primeira resposta, que a ferramenta recomendou e eu aceitei, estava errada. A correção veio logo depois: “para um título voltar à cobrança, o pagamento tem que ter sido estornado antes”.
2. O que acontece com o pagamento de um título que o credor retirou da carteira? A resposta foi que o pagamento prevalece, mas que o credor decide.
3. E se esse pagamento for estornado depois? De novo, o credor decide.

As três apareceram depois da especificação aprovada: a primeira ao detalhar o plano técnico, as outras duas ao escrever o código. Um diagrama de estados do título, com cada transição ligada à regra que a permite, teria mostrado as três antes, como casas vazias numa tabela de “de, para e por quê”.

Verificação e definição de pronto#

A medição de desempenho do terceiro incremento mostrou que a confirmação de 200 mil pagamentos não terminava em 15 minutos, com todos os testes passando. Um envio pela internet mostrou depois que arquivos grandes eram barrados pelo filtro de segurança desde o primeiro incremento: a medição sempre rodou por dentro, sem passar pelo caminho que o usuário usa. E o script de medição ficou quebrado de um incremento para o outro sem ninguém perceber, porque rodá-lo não era obrigatório.

Faltava um documento curto que dissesse duas coisas: que tipo de verificação prova cada tipo de critério (teste no navegador, teste de regra, medição com volume, envio de ponta a ponta, revisão da tela) e o que precisa estar feito para um incremento ser dado como pronto.

Decisões técnicas registradas#

A pasta de decisões técnicas do projeto tinha dois registros: a escolha das tecnologias e uma exceção para correções de segurança. As demais decisões técnicas ficaram nos planos de cada incremento. Entre elas, a de gravar grandes volumes em lote no banco, e não objeto por objeto. Ela estava resolvida na importação da carteira, mas não registrada como regra do projeto. No módulo de pagamentos, a gravação foi escrita do jeito ingênuo, e a falha só apareceu na medição.

Permissões, dados pessoais e operação#

As permissões estão em três especificações. Quando o quarto incremento deu ao perfil Operador a permissão de registrar contatos, um teste do segundo incremento, que afirmava que o Operador só consultava, quebrou. Foi um ajuste de uma linha, mas mostra que nenhum documento tinha a visão de quem pode o quê no sistema inteiro.

As outras duas ainda não custaram nada, e é por isso que costumam passar batido. Um inventário dos dados pessoais, com finalidade, base legal e prazo de guarda, responde à primeira auditoria ou ao primeiro pedido de exclusão. Requisitos de operação, como quanto dado se pode perder e quem é avisado de uma falha, respondem ao primeiro incidente.

Por que especificar por incremento não pegou essas lacunas#

As seis têm uma coisa em comum: nenhuma pertence a um incremento. Um diagrama de estados do título junta regras da carteira, dos pagamentos e, mais tarde, dos acordos. Uma tabela de permissões junta todos os perfis e todas as telas. Uma especificação de incremento, por melhor que seja, olha para dentro. O mapa do todo, por sua vez, era curto demais para mostrar como as peças se encostam.

O que Spec-driven development e Especificação de software defendem continua valendo: especificar tudo em detalhe antes de começar trava a empresa e produz documentos que serão revistos ao primeiro contato com o sistema. Neste projeto, os detalhes mudaram justamente quando havia algo funcionando para olhar. O que mudou é o entendimento do que precisa vir antes: não o detalhe de tudo, mas o todo das questões que cruzam o sistema.

A mudança de método#

A proposta inicial foi a mais forte: documentar todos os escopos mapeados antes de voltar a programar. A decisão final ficou em dois níveis.

O alto nível de todos os escopos é o que mostra as contradições entre eles antes do código. O acordo vai usar o crédito do devedor que os pagamentos criam. A régua de cobrança depende dos limites de contato, que ainda não foram decididos. A fase com várias empresas credoras muda a unicidade de quase tudo o que existe. O detalhe continua perto da implementação, onde ver o sistema funcionando ainda pode mudar a regra.

Há um custo de calendário: a reforma das telas, já especificada, vai esperar o alto nível do sistema inteiro, para que as telas novas já considerem acordos, régua e fila.

Em números#

O que vem a seguir#

Os próximos artigos acompanham os documentos transversais e o alto nível dos escopos restantes, com as contradições que eles encontrarem. Só depois disso a reforma das telas e o incremento de promessas e acordos voltam ao código.