Identação e documentação; coisas de fresco?

Depois de vinte anos trabalhando com desenvolvimento de softwares, ainda me deparo com código que, além de mal feito, peca por sua apresentação. Aprenda, de uma vez por todas, que não só de código funcional vive o mundo.

Diz um certo estudo de uma certa universidade de um certo país que, se as letras de uma palavra estiverem trocadas mas a primeira e última letras estiverem em seus lugares correspondentes, podemos facilmente ler o que está escrito. Um exemplo pode ser visto aqui:

É interessante como o cérebro para certas coisas consegue fazer milagres. Entretanto, para outras, a coisa não é bem assim:

Certamente os mais afoitos vão dizer que o código acima é legível e não terei como discordar. Mas lido por quem? Decerto muito fácil pelo computador que independentemente da apresentação e com sintaxe correta, interpretará e executará esta maçaroca de caracteres.

Mas esquecem estes mais afoitos que não só de computadores é feita a área de programação, mas principalmente de PROGRAMADORES, seja eu, você ou seu colega de trabalho ou faculdade. Dessa forma, um código que não é facilmente interpretado por humanos gera diversos problemas e situações que poderiam facilmente ser evitadas por meio de bom senso e alguns toques a mais no teclado.

Identação não é frescura

Normalmente o programador com boa base escolar ou que aprendeu a programar vendo bons códigos, além de ter uma boa lógica, codifica de tal forma que outros programadores podem facilmente encontrar o que precisam. Certos que o mundo não é uma ilha, organizam o código de forma a facilitar não somente a vida de outros programadores que podem futuramente mexer naquilo que fizeram, mas também a sua própria. Assim, criam funções e classes de forma organizada e, principalmente, identam e comentam o código.

Mas ainda encontro algumas aberrações quando trabalho com códigos de outras pessoas. Muitas vezes para arrumar um pequeno problema, perco mais tempo na procura da função ou classe problemática do que na solução do mesmo. Já sei, vai dizer que existe algo chamado search. Sim, existe. Mas de que adianta esta poderosa ferramenta se o código está tão junto quanto arroz de tropa que, para editá-lo, precisa antes ser organizado? Pouco não é?

Para alguns é desleixo puro. Para outros, falta de conhecimento mesmo. Aos primeiros não tenho muito o que dizer pois simplesmente não estão nem aí. Para os outros, que aprendam de uma vez por todas: código bom não é somente código funcional. E isso vale para todo o tipo de código, ou seja, desde uma simples expressão regular até uma classe em qualquer linguagem orientada à objetos, passando pelo velho e bom HTML, PHP e até mesmo CSS (alô designers!!!). Não basta funcionar. É necessária a manutenção depois.

O mesmo vale para documentação

Isso mesmo, os comentários acima também são válidos para documentação. É praxe para o mau programador ou para aquele que não está acostumado com a área, sair escrevendo linhas e linhas de código sem comentar absolutamente nada. Depois, este mesmo pseudo-profissional gasta horas e horas procurando o que fez quando uma simples linha antes de uma função poderia reduzir em muito este tempo. Preguiça? Má formação? Um pouco de tudo creio eu.

Tempos atrás tive que mexer em um código que fiz em 2008 para acrescentar uma função não prevista na época mas que agora era necessária. Pode imaginar o leitor que teria eu um cérebro de elefante para lembrar do que fiz há quatro anos atrás. Não tive esta necessidade. O código estava comentado, documentado e identado como deve ser. Assim, ao invés de gastar duas horas para resolver o problema, o mesmo foi solucionado em vinte minutos. Claro, depois disso, o changelog foi atualizado e voltei à outras tarefas (como escrever este post).

Já cantava Jorge Bem Jor: “prudência e canja de galinha não faz mal à ninguém”. Então, programe não somente para você. Programe melhor tanto para você quanto para os outros. Identação, comentários e documentação não são frescuras, mas partes tão importantes quanto um código bem escrito.

Acredite, estes pequenos detalhes fazem a diferença entre um bom programador e um mau programador. Procure ver o código de bons programadores, aprenda com eles e deixe as compactações para ferramentas como PageSpeed e outras. Elas podem, depois que você tiver o source decentemente escrito, remover aquilo que acha inútil.

Boa codificação.

PS: na lista abaixo você encontra outros artigos com dias para programar melhor.