Primeiro vamos diferenciar documentação e de comentário. São coisas distintas com objetivos distintos.

E já vamos deixar claro que cada equipe sabe o que é melhor para ela em cada projeto. Há algumas recomendações, experiências que costumam dar certo.

#Documentação

Documentação da API, ou seja, as classes, os métodos públicos é bem interessante documentar, afinal alguém vai consumi-las em algum momento. Pode ser você mesmo que a criou, anos depois 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.

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 isto. Algumas linguagens possuem contratos que podem permitir 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ário 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. Se 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.


  [1]: http://pt.stackoverflow.com/a/15566/101