quarta-feira, 24 de abril de 2013

RTFC é o novo RTFM.

Eu acho que estou lendo uma grande quantidade de código fonte ultimamente. E o código que ando lendo não é nenhum código meu nem mesmo código que eu ajudei de alguma forma a escrever. O código que estou lendo está dentro de bibliotecas e eu estou lendo esses códigos pelo simples motivo de: querer entender o que acontece e como usar esse código.

RTFC é o novo Pretinho Básico RTFM.

Nos últimos meses eu estou envolvido com esse trabalho da última matéria do meu curso superior tecnológico de Sistemas para Internet. O trabalho em questão usa jQuery, Twitter Bootstrap, JSF, PrimeFaces, JPA, Hibernate como EntityManager, EhCache, C3P0, uma dezena de padrões de projeto e, por final, Spring MVC. Uma parte do meu problema está com o fato de que a documentação para alguns desses frameworks na maioria das vezes não ajuda a entender os problemas pelos quais passo para utilizar todo mundo junto. Na verdade, há essa tendência de "convenção em vez de configuração" que alguns consideram como uma coisa boa (ZeroConf) e eu concordaria com isso se fosse fácil decifrar isso. O problema é que usar convenção em vez de configuração não funciona quando ninguém conhece a convenção...


No começo do projeto, eu fiquei muito tempo parado tentando descobrir como integrar algumas coisas meio nada-a-ver, como PrimeFaces e Spring MVC. Em teoria era para funcionar out-of-box. Não funcionou. Só quando eu comecei a olhar o código fonte relacionado eu comecei a entender o que poderia estar acontecendo com meu código. Esse é só um exemplo. Tive problemas com PrimeFaces e jQuery, Hibernate EntityManager com JPA, Bootstrap com PrimeFaces (e com jQuery por tabela), entre outros problemas e (em alguns desses casos) foi olhando o código fonte desses frameworks e debugando através deles que eu consegui resolver a maior parte dos erros (o resto o StackOverflow ajudou).

Uma das vantagens do software livre é exatamente isso. Não há maneira melhor de entender como uma biblioteca ou um framework funcionam que olhando o código fonte. A documentação ajuda, mas quando você inspeciona as coisas mais a fundo e vê os caminhos que a execução toma, você não só resolve seus problemas imediatos como passa a ser um programador melhor, ao se expor ao código e estilo de desenvolvimento de outros programadores.

Eu vejo que reclamar da falta de documentação de determinados projetos de código aberto é como reclamar que não há salada num jantar americano na casa de algum amigo. No entanto, há uma coisa maravilhosa no sofware live que se chama: contribuição voluntária. Se o projeto não possui uma boa documentação, você pode contribuir para com o projeto. Realmente, contribuir com documentação não é a maneira mais nobre de contribuir com um projeto de software livre, mas é uma ótima maneira de ajudar a comunidade e usuários futuros do projeto.

Como a documentação do Spring Security diz:

It is much easier to debug your application or to work out where a problem lies if you don’t treat the external code you are working with as a black box which you never look inside. The first thing you should do when an exception you don’t understand is thrown from an open source library is jump to the class and line number and take a look to figure out what the code was doing there. Otherwise you’re missing out on much of the benefit of using open source code.

Não fique com medo de dar uma olhada no código fonte de uma biblioteca que você usa em seus projetos. Fazer isso irá lhe salvar um monte de tempo (e dores de cabeça) quando estiver desenvolvendo.

Dicionário de siglas:

RTFC - Read the F$%&ing Code
RTFM - Read the F$%&ing Manual

Fontes:

RTFC is the New RTFM