O valor da documentação

Desenvolvedores muitas vezes falam sobre a importância da documentação. Mais especificamente, eles costumam queixar-se de sistemas que não possuem nenhuma. “Como vamos saber o que está acontecendo aqui?”, ou “Bem, acho que alguma coisa é melhor do que nada, mas vamos lá!” e ainda, “Você está realmente esperando que eu leia tudo isso?”.

Certa vez eu estava em uma aula de treinamento Agile quando a questão da documentação veio à tona. O instrutor perguntou se achávamos que a documentação era importante. As respostas foram variadas, mas um rapaz, em particular, estava convicto de que a documentação não é necessária. Quando perguntado o porquê, ele simplesmente disse: “Bem, eu sou desenvolvedor e eu nunca li”.

Curiosamente, apesar de desenvolvedores geralmente não gostarem de ler documentação, eles costumam perguntar por ela. Isso porque quando desenvolvedores solicitam a documentação, o que eles estão realmente pedindo é uma resposta a duas perguntas:

• Eu quero saber o que o sistema deve fazer;
• Eu quero entender por que o sistema foi implementado desta maneira.

O que esta coisa deveria fazer?

Idealmente, um sistema teria documentos que descrevessem os comportamentos executados nele. Para ser particularmente útil, este documento seria específico o suficiente para resolver detalhes de implementação.

A má notícia é que a criação deste documento como um documento é quase inútil, porque o esforço necessário para mantê-lo é proibitivo para a maioria dos sistemas. A boa notícia é que um conjunto bem escrito de testes funcionais provavelmente pode servir a um propósito semelhante e, ao mesmo tempo, ser atualizado automaticamente.

Por que isso funciona assim?

Este é mais complicado. De novo, idealmente haveria alguns documentos que descrevem o processo de pensamento por trás de grandes decisões de arquitetura, algoritmos, etc. E mais uma vez, o custo de manutenção de tal documento, provavelmente, o tornaria inviável. Existem algumas coisas que podem ajudar:

• Auto documentar o código, especialmente descrevendo algoritmos;
• As nomenclatura convencionais facilita oara os participantes do projeto (ex: class Estratégia)
• Comentários oportunos (mas muito limitados) descrevendo os pensamentos por trás de uma implementação;
• Talvez contratos de código

Pensamento final

Não quero dizer que a documentação escrita seja totalmente inútil. Desde que você aceite que a documentação, em algum momento, vai ficar desatualizada, fazer a documentação escrita pode realmente ser útil. Há equipes, por exemplo, que estão usando wikis para compartilhar conhecimento com sucesso muito bom.

***

Artigo original disponível em: http://tatiyants.com/the-value-of-documentation/