Qualquer que seja a realidade, é sempre complicado fazer afirmações concretas quando definimos algum conceito ou defendemos algum ponto de vista. Principalmente quando se trata de um blog pessoal onde o que vale é a idéia do autor na íntegra.
Corro o risco de ser xingado ou ainda estar espalhando bobagem pela internet.
Mas indiscutivelmente, não existe código reusável sem documentação.
Já passei por diversas situações e posso dizer com certeza. Não adianta utilizarmos conceitos estreitamente complexos de desenvolvimento que promovem em sua raiz o reuso como é a OO, se o artefato gerado(código) não tem documentação, definição, explicação sobre o que está sendo tratado naquele trecho.
Quando falo de artefato, não corresponde a documentação de projeto, caso de uso, user history, diagramas e tudo mais. Falo do artefato código gerado no desenvolvimento.
Como já sabemos, desenvolvimento orientado a português estruturado pela análise não funciona, logo o responsável pela organização da estrutura de artefatos, métodos, enfim estrutura do programa, é sempre o desenvolvedor em questão.
Agora, adicione ao fato que o desenvolvedor é responsável pelo artefato, cada projeto trabalhar com N desenvolvedores todos eles com experiências diferentes, idéias diferentes e até grau de conhecimento diferentes.
Em um cenário como este, a única coisa a se esperar é que, ou a organização é plena ou você vai deixar de dormir algumas noites. 
Cada vez mais, buscamos desenvolvimento ágil e eficiente dentro da TI como um todo. E isto está diretamente ligado ao reuso que é o termo abordado neste tópico.
Ai a grande questão é, como fazer reuso de um código que você não faz a mínima idéia do que faz ?
Sei que uma boa organização, padrões e ainda grande coesão interferem muito nisso. Mas qualquer que seja o cenário proposto, um código bem documentado faz toda a diferença.
Basta você pensar logicamente e ver que qualquer um que for utilizar um código não documentado, terá que no mínimo analisá-lo por completo para poder ter noção do que se trata. Se é para ter código reusavel onde todos que forem reusar precisam revisar a implementação, as vezes é mais fácil escrever todo o código denovo para uma tarefa específica.
Imagine algo do gênero (Em Java):
public String gera(int p, String text) {
return (p > (p + 0xFF * 14)) ? text.replaceAll("[./-]*YY+(879)", ",") : text;
}
Ao ver um troço desses a única expressão na minha cabeça é “WTF ??”.
Tubo bem, que fui um pouco longe demais, mas estes exemplos com hexadecimal, expressões regulares e ternários sempre convencem.
Aprenda de uma vez por todas, a não ser que a sua intenção é fazer um código que só você (ou nem você) poderá dar suporte(isso claro nos próximos 15 dias até você esquecer tudo) , documente seu código.
Lembre da premissa, comentários nunca são demais. Você não será chingado por documentar seu código demais. Mas será se trabalhar comigo e não o fizer.
Uma coisa interessante é notar que, se você faz sua parte, qualquer que seja o desenvolvedor que não tenha esse hábito e trabalhe em projetos onde você trabalha acaba também adotando está pratica. Se você duvida disso tente, os resultados são assustadores e claro positivos para todo mundo.
Tenha amor ao próximo, se não faz por você faça pelos outros. 
update: 19/12/2007 - Syntax Highlighter
update: 25/01/2008 - Correção de escrita.
07, Dezembro 2007 17:47
Interfaces fluentes, testes unitários, refactoring e nomes sugestivos são mais eficientes que comentários. Quando não restar alternativa, comente.
08, Dezembro 2007 17:02
Quanto a fluent interfaces e nomes sugestivos concordo plenamente que auxiliam muito nisso. Mas quanto a testes unitários, voltamos ao problema de ler linhas e linhas de código para encontrar a solução(is bad)
;
Mas um detalhe simples, fluent interfaces e nomes sugestivos não explicitam exceções lançadas (que vide contrato será trabalhada) ou fluxos alternativos.
Valeu pela comentário Bruno.
Até mais.
23, Dezembro 2007 17:34
Não sou lá muito amigo dos comentários. Concordo com o Bruno, acredito que deve ser utilizados em último caso. O exemplo dado por você foi infeliz, pois não é um código que precisa de comentários, mas sim um código muito, mas muito mal escrito.
24, Dezembro 2007 00:10
Nomes sugestivos e fluent interfaces são uma ótima instrumentação para produzir software, não questiono em nenhum momento isso.
Mas não posso concordar com as afirmações feitas quanto a documentação.
Não importa o quanto sugestivo seja, qualquer programador(desenvolvedor, coloque o nome que quiser aqui) tem uma maneira de pensar, uma bagagem técnica própria, e isso faz com que este tenha idéias diferentes e estilos diferentes de desenvolvimento. Portanto o que você diz ser sugestivo, certamente, não condiz diretamente com o raciocínio de todos a sua volta.
A menos que se desenvolva software utilizando uma DSL própria para o negócio e estrutura de desenvolvimento, não é possível afirmar que documentação é desnecessária, ou necessidade de ultimo caso.
Obrigado pelo comentário Rodrigo, são pensamentos diferentes que produzem avanço em nosso segmento.
Até a próxima.
29, Dezembro 2007 17:22
Normalmente quem não pega código de outros, não precisa de documentação. Gosto do Manifesto Ágil , mas documentação ZERO não é uma boa interpretação para “Software em funcionamento MAIS que documentação abrangente”.
Realmente ler código para entender não é bom. Se pudermos contar com a documentação para saber O QUE o componente faz e o código com todas as características que gostamos (Interfaces fluentes, testes unitários, refactoring e nomes sugestivos) para saber COMO ele funciona, seria o ideal.
Para fechar, a documentação não deve ser massacrante e sim um instrumento para melhorar o código. Gosto de dizer: “Documente com Moderação.”
29, Dezembro 2007 21:12
Raphael deAlmeida wrote: “Para fechar, a documentação não deve ser massacrante e sim um instrumento para melhorar o código”.
Perfeito, é exatamente disso que falo.
Talvez tenha sido mal interpretado, desculpe.
Quando digo “documente sempre”, quero dizer “não tenha preguiça de documentar” ou “uma documentação simples, as vezes pode poupar horas de um colega seu”.
Obrigado pelo comentário Raphael.
Até.
23, Fevereiro 2008 10:45
“Não importa o quanto sugestivo seja, qualquer programador(desenvolvedor, coloque o nome que quiser aqui) tem uma maneira de pensar(…)”
Por isso toda empresa séria tem padrões de codificação. Se existe um padrão de codificação e se os nomes forem sempre sugestivos, comentários podem virar exceção. Na filosofia comentários para tudo, corremos mais riscos de ver códigos malucos como o método public String gera(int p, String text);
O cara pensa “É só colocar um comentário”.
23, Fevereiro 2008 16:05
Oi Tadeu.
Bom, eu realmente não tento pregar que a documentação de código é a única premissa sobre o desenvolvimento de software que garante qualidade(Na verdade nenhuma delas garante).
E concordo que padrões são bem vindos (quando saldáveis). Mas padrões tem seu contexto, e não são aplicáveis a negócio.
Ultimamente tenho estudado mais interfaces fluentes a TDD e DDD, e estou chegando a conclusões não vistas antes, vendo que trabalhar com estas bem aplicadas, pode ser bastante sadio para o reuso.
Mas todas as técnicas são bem vindas quando agregam ao resultado.
E independente de cultura IMHO, pegar um código desenvolvido por outro porém bem documentádo é algo que pode salvar o nosso dia.
Obrigado pelo comentário.