Quando você fala nos detalhes sórdidos (“bases de dados, queries, estruturas de dados, rede, integrações com outra bibliotecas, etc…”), você está falando de um nível de abstração mais próximo das estranhas da tecnologia.

Por exemplo: O Vendedor pode ter um um método efetuaPedido() que verificaEstoque() e que gravaPedido(). Se você não estiver interessado na implementação da efetuação de pedido isso basta.

Mas se você estiver corrigindo um bug nesse código pode te interessar ver como a verificação de estoque é feita ou a gravação de pedido. Aí, você vê que verificaEstoque() chama um Webservice e que a gravaPedido() manda uma mensagem para um Mainframe. Ou outras coisas sórdidas do gênero…

Aplico esta ‘técnica’ sempre, sempre que possível, pois torna a leitura e compreensão do código não só mais fácil como agradável. Um exemplo simples está na linha 104 de uma classe do meu projeto LJColligo.

Um exemplo já bem melhor está em um código de testes que eu fiz algumas semanas atrás.

E tem gente que acha que eu não codifico mais aqui na FICO…

PS: Creio que em muitos ‘momentos’ o bom e velho comentário é indispensável, mas usar nomes altamente descritivos (para identificadores em geral) são essenciais também.

What makes APIs hard to learn? Answers from Developers http://www.computer.org/portal/web/computingnow/1109/whatsnew/software

Apesar de em geral o termo API ser usado pra interfaces que você expõe à terceiros, eu gosto de considerar que toda interface de qualquer tipo de módulo é uma API (por exemplo, uma classe em Java, uma função em Haskell e assim por diante).

Se você extrapolar os insights daquele artigo de APIs pra qualquer código, mesmo interno, então uma das coisas que mais importam é entender o motivo pra API funcionar de certa forma. Em geral é fácil de entender “o que foi feito” olhando pra interface, mas entender o porquê é bem mais difícil.

E note que a solução do artigo não é escrever mais documentação pra cada método, mas sim escrever documentação da arquitetura e dos princípios gerais usados na API. Ou seja, se você entender a arquitetura geral do programa, vai ser mais fácil entender porque um método está se comportando de certa maneira.

E nisso concordo 100%.

Mas é o comentário mais difícil de se escrever, pq vc só sabe se escreveu direito quando não lembra o porquê fez daquele jeito. Tipo da coisa que exige prática, o que implica em errar bastante antes de acertar =/

1. Explicar uma computação/cálculo complicado
2. API’s liberadas para terceiros (papel dos criadores de frameworks, bibliotecas)

Nomes de métodos e variáveis devem ser auto-explicativos. Pequenos blocos devem ser extraídos em métodos (mesmo blocos de uma linha!!!!!), tudo para auxiliar na legibilidade do código.

Você usou 3900 toques pra reclamar da falta de comentários em interfaces de código Java? É isso?