A falácia da documentação de código

19/10/2013

Esta é a tradução de The code documentation fallacy de Jussi Pakkanen.
Digamos que você comece a trabalhar em uma nova base de código. Será que você, como um usuário, prefire ter 90% ou 10% das suas funções de API comentadas no Doxygen ou algo semelhante?

Usando meus poderes psíquicos eu suspeito que você escolheu 90%.

Parece ser a coisa óbvia. Muitas empresas ainda têm um mandamento que todas as funções da API (ou >90% delas) devem ser documentadas. Não ter comentários é apenas ruim. Isto parece como uma questão acéfala perfeitamente óbvia.

Mas é realmente?

Infelizmente, existem alguns problemas com essa hipótese. A principal delas é que os comentários serão escritos por seres humanos. O que eles provavelmente acabam fazendo é algo como isto.

/*
 * Takes a foobar and frobnicates it.
 *
 * @param f the foobar to be frobnicated.
 * @param strength how strongly to frobnicate.
 * @return the frobnicated result.
 */
int frobnicate_foobar(Foobar f, int strength);

Isto é algo que eu gosto de chamar de documentação por palavra de ordem aleatória. Agora podemos fazer a pergunta realmente relevante: quais informações adicionais esse tipo de comentário fornece?

A resposta é, obviamente, absolutamente nada. É só barulho. Não, na verdade é ainda pior: é o ruído que tem uma grande probabilidade de estar errado. Quando algum programador muda a função, é muito fácil esquecer de atualizar os comentários.

Por outro lado, se apenas 10% das funções são documentadas, a maioria das funções não tem quaisquer comentários, mas as que têm algo, provavelmente, será como isto:

/**
 * The Foobar argument must not have been initialized in a different
 * thread because that can lead to race conditions.
 */
int frobnicate_foobar(Foobar f, int strength)

Este é o tipo de comentário que é realmente útil. Naturalmente, seria melhor para verificar a condição especificada dentro da função, mas às vezes você não pode. Tê-la em um comentário é a coisa certa a se fazer nesses casos. Não tendo toneladas de documentação lixo faz esses tipos de comentários se destacarem. Isso significa que, paradoxalmente, que ter menos comentários leva a melhor documentação e experiência do usuário.

Como uma estimativa grosseira, 95% das funções em qualquer base de código devem ser tão simples e específicas que a sua assinatura é tudo que você precisa para usá-las. Se elas não estiverem, o design da API falhou: de volta à prancheta de desenho.

Leia também Readme Driven Development

Marcadores: documentação