O papel da documentação de software nas metodologias ágeis

As razões para essa frase aparecer no Manifesto Ágil são várias, mas, para mim, a mais impactante é que, quando temos uma documentação extensa, frequentemente cria-se a ilusão de que não precisamos conversar com o cliente e entendê-lo melhor, já que o documento (supostamente) cobriria essa função.

No entanto, esse pensamento se baseia em pontos perigosos: assume-se que quem escreveu a documentação realmente entendia do negócio, que essa pessoa (ou comitê) conseguiu escrever de forma clara para todos os indivíduos que a consumirão, que esses indivíduos vão interpretar o texto bem e ninguém esquecerá de detalhes potencialmente muito importantes... e de que esse documento será sempre atualizado, conforme as mudanças aconteçam.

Na prática, a frase do Manifesto significa que evitamos desperdiçar tempo com documentações que não serão lidas ou que ficarão obsoletas rapidamente. Em vez disso, preferimos que o próprio software seja sua documentação, através de:

Testes de unidade automatizados: código que verifica um método/função/classe que, para um dado cenário controlado, a saída esperada é tal. Essa é uma documentação para o desenvolvedor que for alterar esse código interno no futuro.

Testes de aceitação automatizados: código que simula o que o usuário do sistema fará, seu comportamento usando uma funcionalidade. Essa é uma documentação para quando o time for alterar o que um determinado código faz.

Clean code: prática de trabalhar ativamente para deixar o código claro e coeso, para que o próximo que venha a mexer nele não precise gastar tempo desvendando o que ele faz. Esse é um guarda-chuva gigante de boas práticas no dia-a-dia de desenvolvimento.

Se o código ainda não está bom, a ponto de qualquer um entendê-lo... Documentação dinamicamente gerada: geração automática, através de ferramentas específicas de cada linguagem, da relação entre as partes e classes do sistema. Frequentemente, usa-se UML aqui, e há diversas ferramentas que analisam um código e geram os diagramas que refletem o estado atual do design e arquitetura do sistema.