Eu sou um defensor de comentar sobre o código fonte e documentar os produtos de software. É minha experiência pessoal e observação que trabalhar no código fonte que é rigorosamente comentado me ajudou de maneiras diferentes quando tive que cultivar software ou mantê-lo.
No entanto, há outro campo que diz que comentar não vale nada ou que seu valor é questionável. Inúmeros defensores da codificação sem comentar argumentam que:
- Se um pedaço de código é bem escrito, é auto-explicativo e, portanto, não precisa ser comentado
- Se um trecho de código não for auto-explicativo, refatore-o e faça-o auto-explicativo para que ele não precise de comentários
- Sua suíte de testes é sua documentação ao vivo
- Com o tempo, o código e os comentários ficam fora de sincronia e se tornam outra fonte de dores de cabeça
- O Agile diz que o código de trabalho é mais importante do que pilhas de documentação, para que possamos ignorar com segurança os comentários escritos
Para mim, isso é apenas dogma. Mais uma vez, minha observação pessoal foi de que o software escrito por equipes de desenvolvedores inteligentes e experientes acaba tendo uma quantidade considerável de código que não é auto-explicativa.
Novamente, a API Java, API Cocoa, API Android, etc. mostram que se você deseja escrever e manter documentação de qualidade, é possível.
Dito tudo isso, conversas sobre prós e contras da documentação e comentários sobre o código fonte baseados em crenças pessoais geralmente não terminam bem e não levam a conclusões satisfatórias.
Como tal, estou procurando trabalhos acadêmicos e estudos empíricos sobre os efeitos da documentação de software, especialmente comentando o código-fonte, sobre sua qualidade e manutenção, bem como seus efeitos sobre a produtividade da equipe.
Você já se deparou com esses artigos e qual foi o resultado deles, se houver?