Documentando

Estou muito satisfeito com a bolsa de iniciação científica, a qual começou oficialmente este mês.

O meu objetivo, durante meu trabalho lá, será implementar a paralelização do código do MClone, a.k.a, a implementação do trabalho de doutorado do meu professor. Quando peguei o código pela primeira vez, ele estava uma bagunça (ainda está). Desde o seu desenvolvimento inicial, em torno do ano de 1999, um bom número de pessoas, para diferentes fins, modificou o código do MClone. Como elas gostariam dos créditos de sua modificação, causaram um monte de poluição incluindo comentários do tipo "modificado por 'insira_nome_aqui' em 'insira_data_aqui'". Além disso, como não tinham o objetivo de manter o código usável para outrem num futuro distante, não parecem ter se preocupado muito com a legibilidade, mantendo comentadas (das mais variadas formas possíveis) as partes "obsoletas".

Em um certo momento, no início do ano, quando eu comecei a entrar em contato (contato muito frágil, digamos assim) com o programa, percebemos a bagunça. Algumas partes estão muito bonitas, com código limpinho e bem documentado. Outras partes estão complicadas, cheias de comentários aleatórios de código antigo e estruturas de dados com nomes nem um pouco convencionais (e.g., tem uma lista encadeada com o nome de Array). No meio do semestre passado, pegamos cada arquivo e demos uma olhada em o que cada coisa faz. Decidimos que faríamos uma série de classes e reestruturaríamos tudo. Apesar de eu participar dessas reuniões, muito pouco mexi no código até agora: quem mais arrumou (e fez um ótimo trabalho, reestruturando em pastas as classes -- antes, como o código era majoritariamente em C, quase nem víamos classes; agora, as coisas já estão encaminhando, creio --, sempre versionando através do projeto do MClone que a gente criou no GoogleCode) tudo foi o mestrando que trabalhava comigo.

Agora, no início do semestre, voltei a mexer no código. Como precisava conseguir compilar o programa no Ubuntu que eu instalei numa máquina lá da Computação Gráfica, e como pretendia utilizar o Eclipse, e como ao programa faltava um Makefile (acho que ele se perdeu no meio das reestruturações), resolvi documentar tudo, desde o que se deve fazer para compilar utilizando o Eclipse até como é que se faz para instalar as bibliotecas necessárias ao programa. Foi isso que fiz durante quase o dia inteiro de quarta-feira, e isso que pretendo terminar de fazer na segunda-feira.

Documentando o código, percebi algo interessantíssimo: eu ADORO documentar. Adoro escrever explicações sobre de que forma é possível fazer algo que não seria óbvio para qualquer um.

Lendo A Catedral e o Bazar, do Eric Raymond, esses dias, eu me deparei com a seguinte frase (negrito feito por mim):

Many people (especially those who politically distrust free markets) would expect a culture of self-directed egoists to be fragmented, territorial, wasteful, secretive, and hostile. But this expectation is clearly falsified by (to give just one example) the stunning variety, quality, and depth of Linux documentation. It is a hallowed given that programmers hate documenting; how is it, then, that Linux hackers generate so much documentation? Evidently Linux’s free market in egoboo works better to produce virtuous, other-directed behavior than the massively funded documentation shops of commercial software producers.

Eu não sou lá um programador grande coisa... então acho que posso ser bom em documentar (e gostar disso), mesmo, né?

Finalmente, meu professor estava reclamando sobre o fato de que o porte que uma das pessoas que mexia no código antigamente fez para Mac não funciona no computador dele. Sinceramente, acho que após as minhas pequenas arrumações há uma relativa chance de que o programa passe a funcionar no computador dele também - o que seria algo bem legal, né?

Era isso, enfim... o todo foi mais para explicar que eu percebi que gosto de fazer documentação u.u

R$