Primeiro vamos diferenciar documentação e comentário. São coisas distintas com objetivos distintos e por isso tratamos de forma distinta. E já vamos deixar claro que cada equipe sabe o que é melhor para ela em cada projeto. Há apenas algumas recomendações, experiências que costumam dar certo. # Documentação Documentação da API, ou seja, as classes e os membros públicos, é bem interessante documentar, afinal alguém vai consumi-las em algum momento. Pode ser você mesmo que a criou, anos depois vai usar e não lembrar de como fazer. Melhor ter uma documentação dentro de um padrão estabelecido do que ter que ficar lendo o código para saber como usá-lo. Embora isto costume estar junto do código, ele não faz parte do código propriamente dito. É bom estar perto para facilitar qualquer alteração quando o código altera. Se bem que mudanças no código não deveriam forçar mudanças na documentação. Mas isto já é outro assunto. Há controvérsias se deve documentar formalmente métodos privados. A maioria dos programadores consideram que um comentário simples já é suficiente, ou mesmo nada quando o método é auto descritivo e não tem nada realmente útil que acrescente algo. A documentação da arquitetura também é fundamental para qualquer pessoa entender como tudo funciona. Normalmente ela é separada completamente do código. São textos e diagramas explicativos de forma ampla. # Testes Testes podem ser usados como forma de documentação alternativa. Mas eles não substituem um texto comum. Eles funcionam mais como uma documentação técnica mostrando como os componentes devem responder. Ao invés de dizer que um método sempre deve retornar um número positivo, você faz um teste que verifica se isto está sendo feito corretamente. Algumas linguagens possuem contratos que permitem isto no próprio código. # Comentários Comentários devem ser usados especialmente quando o código não consegue expressar o que está acontecendo ou faz algo que não é muito intuitivo. Comentários servem para explicar **porque** está fazendo aquilo. Comentários dizendo **o que** está fazendo beiram o ridículo e realmente só servem para ajudar novatos entenderem melhor o que está acontecendo, servem para aprender. São comentários didáticos que não devem ser usados em códigos em produção. Na maior partes das vezes quando vemos comentários dizendo o que a linha faz, é redundante. - Está confuso? Torne mais simples. - Não deixa claro o que é aquilo? Dê melhores nomes. - Está destacando o bloco? Separe em métodos menores. Dei uma [resposta mais profunda sobre isto][1]. # Dicas para aprender documentar Procure ver como os bons projetos fazem a documentação e se inspire neles. As ferramentas existentes hoje para ajudar formatar a documentação já dão dicas do que ela deve conter. Mas lembre-se de não falar de obviedades, além de não esquecer de informações importantes, especialmente quando pode provocar problemas ou comportamentos inesperados. [Coloquei no **GitHub** para referência futura][2]. [1]: https://pt.stackoverflow.com/a/15566/101 [2]: https://github.com/maniero/SOpt/blob/master/Conceptual.md