Quem consegue ler isto? Legibilidade de código e o trabalho em equipe

A legibilidade de código pode parecer uma coisa boba quando se olha para ela à primeira vista, mas tal como a gramática da linguagem humana, tem um mesmo objetivo:

Estabelece regras, formatos para que quem escreve se faça entender por outras pessoas, de forma que a mensagem que se deseja passar seja entendida clara e objetivamente.

Afinal de contas, "pra" que raios serve essa tal legibilidade? Bom, da mesma forma que um livro escrito em português, inglês, espanhol, seja lá qual for seu idioma, essa tal legibilidade (palavrinha difícil, mas muito nossa amiga) serve para duas coisas:

1. Facilitar a compreensão das coisas;

2. Não tornar cansativo o processo da compreensão.

Hoje ainda, esbarrei em uma frase (velha, até) que dizia:

"Qualquer programador é capaz de escrever códigos que um computador possa ler, mas apenas bons programadores são capazes de escrever códigos que podem ser lidos (e entendidos) por outros programadores."

Assim, podemos encarar um código como um livro que conta uma história: qualquer livro que tenha formato de "tijolo" (tamanho/peso, literalmente falando) torna complicada e cansativa a compreensão das ideias. 

Neste ponto, a pergunta: "O livro tem figurinhas?" também teria algum sentido, porque algumas pessoas até evitam ler livros em formato de "blocos" de texto justamente porque não chamam a atenção e até embaçam a visão daqueles mais cansados, ou que usam óculos (meu caso).

Na verdade o código é mais ou menos parecido neste ponto: Um código 'tijolo' tem suas ideias expostas de maneira mais complicada. Nem sempre a gente entende de que é feito o tijolo se não passar pelas ideias duas, três ou mais vezes...

Se isso é complicado para uma pessoa que lê o seu código, imagine quando ele passa por dois, três pares de olhos (ou mais) durante seu ciclo de desenvolvimento e/ou manutenção? A cada passada, o código tem de recontar sua história novamente, e novamente.

Pois bem, como tijolos são pesados e folhas de árvore são mais leves, podemos comparar um código "limpo"  a uma folha de árvore, com suas estruturas bem definidas, da maior para a menor, principal até a secundária, e assim por diante.

Fica muito mais fácil, principalmente se pegamos "o bonde andando" e temos que nos "sentar no lugar do maquinista". Para ficar claro, precisamos colocar algumas regras na redação, igualzinho a uma gramática. Vamos lá?

a) Quando os elementos "nascerem", batize-os apropriadamente - Crie nomes para os seus elementos de forma que, ao ler estes nomes, tanto na declaração quanto no código, quem está lendo saiba o que eles significam.

Exemplo:

$a = 2;
$b = 3;
$s = $a+$b;

Use, para facilitar:

$nroA    = 2;
$nroB    = 3;
$nroSoma = $nroA + $nroB;

b) Escreva nomes de variáveis o mais curtos possível, e o mais significativos possível - Esta regra propõe que se aproveite o melhor possível o espaço que se tem para escrever. As linguagens de programação limitam a quantidade de caracteres, cada uma a seu modo, mas tente utilizar uma convenção baseado em "evitar o tijolo". Nomes muito longos de variáveis são complicados de entender.

Exemplo:

$numerodacarteiradeidentidade = 123456

Talvez fique melhor como:

$nrCartIdent = 123456

ou ainda:

$nrCI = 123456

c) Padronize os nomes dos elementos - Procure utilizar uma notação que deixe claro ao utilizar um elemento o seu tipo e função, por exemplo. Algumas fontes falam em utilizar a notação húngara de nomes de elementos, que permita que pessoas que não participaram do desenvolvimento (revisores de código e testadores) entendam o que está escrito e possam apontar sugestões ou correções.

Exemplo:

$nroTeste = 1234;
$txtTeste = "Nome da pessoa";

Como sugestão, podemos ver a nomenclatura acima, analisando:

• Primeiros três caracteres minúsculos - tipo de informação a armazenar
• Restante do nome com a primeira letra maiúscula (com uma palavra), ou a primeira de cada palavra (com duas ou mais palavras no nome)

d) Coloque seu código em níveis - Procure utilizar um mecanismo de indentação (do inglês indentation, recuo em português), para facilitar a organização das estruturas de controle do seu código, facilitando a leitura e a manutenção das linhas.

Assim, um código sem os recuos fica:

if (isset($nrTeste)) {
echo $nrTeste;
} else {
echo "Sem valor";
}

Meio "pesado" para ler, não? Então vamos tratar de deixar a coisa com mais "curvas" (e aqui eu me lembro do Oscar Niemeyer, que dizia que "Se a reta é o caminho mais curto entre dois pontos, a curva é o que faz o concreto buscar o infinito"):

if (isset($nrTeste)) {
   echo $nrTeste;
} else {
   echo "Sem valor";
}

e) Coloque um limite na quantidade de colunas do seu código - Procure usar um limite de colunas (caracteres) de mais ou menos 80, (sim, como em COBOL) para que suas linhas fiquem dentro de uma área da tela que se possa ler sem usar barras de rolagem, agilizando a leitura.

f) Use o alinhamento de sinais de atribuição como aliado - Uma coisa importante que aprendi, sobre simetria: É mais fácil lermos e localizarmos alguma coisa se tivermos uma referência comum para nos guiar. Geralmente um operador nos chama mais a atenção do que um nome, à primeira passada de  olhos.

Veja:

$nrA = 1;
$nrBC = 3;

Pode ficar melhor assim:

$nrA   = 1;
$nrBC  = 3;

Desta forma conseguimos separar variáveis e valores e ler/localizar rapidamente a informação de que precisamos, não é mesmo?

f) Utilize-se de quebras de linha e "pausas para respirar" - Tal qual os parágrafos de uma página, às vezes precisamos de "pausas", para que a leitura não seja por demais cansativa aos olhos e à mente.

Uma vez um professor e grande amigo me disse que três ou quatro linhas por parágrafo são suficientes para "evitar a fadiga". Pois bem, se ele estava certo, você leu todo este texto e chegou até aqui sem cansar (muito).

No caso das quebras de linha de código, podemos quebrar as linhas e alinhar os sinais, e também separar as linhas em pequenos blocos, por atribuição ou funcionalidade, para facilitar a localização das linhas que precisamos compreender.

Veja só:

$this->load->model('dados_model');
$this->load->model('fichas_model');

$this->load->helper('ajudante');
$this->load->helper('faxineiro');

é mais organizado do que este, por exemplo:

$this->load->model('dados_model');
$this->load->helper('ajudante');
$this->load->model('fichas_model');
$this->load->helper('faxineiro');

Neste ponto, temos um código mais organizado, de forma que as models e helpers ficam agrupadas por tipo/função, facilitando que se possa incluir uma ou outra de um jeito que outras possam, além de ler, dar a manutenção necessária, de uma forma mais rápida.

g) Comente e Documente seu código - Procure comentar trechos de código que precisem de explicações adicionais, e procure documentar o cabeçalho de cada arquivo e função que escrever, da forma mais clara e sucinta possível.

Com isso, é mais fácil utilizar geradores de documentação de código automatizados como o PHPDoc e o JavaDoc, caso seja necessário, sem falar que facilita a compreensão de sistemas de qualquer tamanho e de qualquer idade (sim, o passar do tempo nos faz esquecer as coisas).

Conclusão

Bom, depois de todas estas observações e regras, fica clara a necessidade de se organizar o código de uma maneira legível, principalmente se este código pode passar por outras pessoas, independente de passar por uma, duas ou trinta. Mesmo assim, não esqueça de revisar seu código com calma antes de passá-lo adiante, para que você tenha um número mínimo de coisas a reestruturar, se necessário.

Procure manter o bom hábito de tornar seu código legível e documentá-lo. Além disso, espalhe a boa prática a seus colegas e seus amigos que também trabalharem na área. Com o tempo, isto pode ser de grande ajuda no dia-a-dia.

Por hoje é só, pessoal! Até a próxima!