Refatorando Padrões

Vejo muitos que programam perfeitamente, orientado a objetos, seguindo padrões a risca. Comentam entusiasticamente em fóruns sobre seus novos frameworks, linguagens e bibliotecas, querem é claro, angariar novos adeptos. De fato, boa parte desses projetos são maravilhosos em suas descrições, isso quando há uma descrição…

O ponto onde quero chegar é que na maioria dos projetos que vejo, a documentação é escassa, não há tutoriais ou documentação sequer no código fonte.

Quanto a documentação em código, eu reconheço o que Rod Johnson, criador do Spring, sabiamente afirmou em seu célebre livro Expert One-on-One J2EE Design and Development, um código bem escrito, seguindo padrões claros, sem classes, métodos ou variáveis obscuros, não necessita de documentação, o código fala por si, qualquer programador olha e entende sem medo, mas isso serve somente para quem participa do projeto.

O problema é que ninguém está interessado em olhar dúzias e dúzias de classes para entender como usar. São necessários tutoriais e documentação farta para que consigamos manter alguém usando o que criamos, por melhor que ela seja.

O criador se desespera, óbvio que para muitos é maçante documentar código, mas é necessário, e não é preciso escrever duas vezes, uma em código e outra em documentação pública. São muitas as ferramentas que resolvem o problema. Mas lembre-se que é necessário documentar seguindo padrões, para o pessoal de Java, use JavaDoc, embora limitado/criticado por muitos, é muito fácil de ser utilizado, quantos já não recorreram a documentação do JDK, alguém teria a paciência de ter lido o código ? Eu já tive que ler código várias vezes em muitos frameworks sem documentação, sendo que um mero comentário explicativo na documentação da classe teria resolvido o problema rapidamente.

Eu não sou muito fã da Microsoft, mas tenho que dar o braço a torcer, felizes os usuários do MSDN, quando necessito tirar uma dúvida quanto ao uso de CSS, HTML, ou outras áreas relacionadas, vou direto nele, tudo bem explicado e com ótimos exemplos. A Microsoft pode até não abrir o código fonte de suas ferramentas, mas ela compensa muito bem isso fornecendo aos seus usuários toda a documentação necessária para utilizá-la.

Então na próxima vez que alguém reclamar que seu framework é complicado, para e pense um pouco? “Será que tenho bons tutoriais e documentação ? Será que descrevi de forma concisa o que ele faz ?”. Não espere que o usuário simplesmente baixe e fique tentando adivinhar como usar, não o chame de estúpido, o código do framework/biblioteca é simples para você que criou.

O usuário terá que perder um tempo precioso estudando, e a não ser que seja algo revolucionário, existem alternativas para vários frameworks/bibliotecas. Temos que aprender a cada dia, cada vez mais, não temos tempo a perder tentando adivinhar o que foi codificado. Queremos algo claro e rápido, bem documentado, para finalmente decidir se vale a pena investir tempo.