Com o advento e crescimento dos projetos Open Source, se intensificou o conceito de que em última instância a melhor documentação de um projeto é o seu próprio código fonte. Concordo plenamente com isso! Em projetos ativos, manter uma documentação sobre arquitetura completamente atualizada é uma tarefa ingrata (sobretudo se seguirmos os moldes de artefatos exigidos pelas metodologias waterfall), e documentação errada é a pior coisa que pode existir.
Em projetos Open Source, onde os recursos são muitas vezes escassos e não se pode dar o luxo de manter uma pessoa apenas para manter tudo atualizado, a necessidade de uma documentação simplificada impera. E a necessidade de um código organizado também.
O problema é que muita gente levou ao pé da letra esse conceito, e chegou-se à conclusão de que comentários são supérfluos, afinal o próprio CÓDIGO é a documentação. Resultado: tenho cada vez mais visto toneladas de linhas de código sem um puto de um comentário.
Ah, mas com nomes incrivelmente sugestivos: apagaORegistroDoUsuarioEMandeMensagemdeDesolePraEle.
Senhores e Senhoras, o código fluente!
Plagiando um exemplo que eu peguei no iMasters:
Vendedor.deNome("Abreu").
vende().
paraCliente("Rafael").
oProduto("Mouse Verde").
oProduto("Teclado de Pano").
comDescontoDe(20).
mostrandoDetalhes();
O problema é que por mais que se empacote todas as funções com nomes extremamente sugestivos, que se crie DSLs para se esconder a complexidade, que as variáveis sejam extremamente bem nomeadas, alguma hora os detalhes sórdidos do código vão começar a aparecer: bases de dados, queries, estruturas de dados, rede, integrações com outra bibliotecas, etc…
(Aaaaaaaaa, você não trabalha com bibliotecas, nem com BD, nem com rede, e apenas integra código fluente? Meus pêsames, o mundo da computação é bem mais interessante e divertido do que isso. Próximo…)
E na hora que chegamos aos detalhes sórdidos, por mais que o nome do método explique o que está se fazendo, pode ficar a dúvida: porque o método faz isso desta forma? E entender o porque das coisas é essencial se você está tendo que corrigir/modificar/aprimorar/integrar/analisar código legado. Sim, porque o que torna o código legado tão infernal de se mexer é justamente entender O QUE SE PASSAVA PELA CABEÇA DO DESGRAÇADO QUE ESCREVEU AQUILO!
Exercício: pegue um código que você escreveu há 6 meses atrás, de um projeto do qual você não participa mais, e tente entender todas as minúcias….foi sofrido? Imagino que sim. Agora imagine o pobre coitado do estagiário que está tendo que resolver um bug que ocorre naquele trecho!
Muito se fala por aí que código tem que ser escrito para ser lido por seres humanos e não por máquinas. Uma máquina apenas interpreta aquilo que escrevemos, e não está nem aí se faz sentido ou não. Ao contrário de seres humanos. Todos ficamos muito felizes quando entramos no javadoc da Sun, e encontramos alguns detalhes de implementação interessantes de métodos cujos nomes muitas vezes são bem explicitos. Como por exemplo o remove(String key) de uma Collection. Ninguém tem dúvidas do que ele faz, mas o que acontece se eu passar um valor nulo? Ou se passar um objeto que não existe?
Comentários são uma ferramenta muito útil, presente em qualquer linguagem, e que fazem parte do código. Devem ser utilizados com inteligência, para facilitar a vida de todo mundo, tornar o código realmente uma documentação completa e inteligente e poupar horas, cabelos e neurônios de desenvolvedores cansados, estressados ou que simplesmente não querem passar horas decifrando a mente alheia.
Péra aí…
Você usou 3900 toques pra reclamar da falta de comentários em interfaces de código Java? É isso?
Link | December 7th, 2009 at 14:04
Vale pra C, C , Python, Java, Brainfuck. Mas resumindo, é isso.
Link | December 7th, 2009 at 14:05
Na minha opinião, o comentário deve explicar o que foi feito e não como foi feito. Eu ainda sou fã da idéia que o comentário deve ser necessário APENAS nos seguintes casos:
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.
Link | December 7th, 2009 at 15:05
Só acho que o ponto da interface fluente ficou em muito destaque, enquanto o ponto real é: “comentário explicando o motivo que levou ao código”.
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 =/
Link | December 7th, 2009 at 17:29
Meu orientador me mandou um artigo interessante:
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.
Link | December 8th, 2009 at 12:57
Conheço este conceito por: “Human Interface” operations, termo difundido (ou até cunhado) pelo Fowler já desde 2005.
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.
Link | December 11th, 2009 at 14:19
Acho interessante a idéia do Uncle Bob de que os métodos tem que ter o mesmo nível de abstração.
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…
Link | January 20th, 2010 at 19:23