Faz um tempo que venho observando códigos que considero estranhos. Apesar de entendê-los, são necessários um esforço e um tempinho disponível. Alguns ainda exigem uns debugs ou até mesmo perguntar ao autor qual foi a intenção daquele trecho.

Baseado nisso e no comentário que recebi recentemente e inspirado pelo post de um amigo, vou fazer uma lista de coisas que proponho. São coisas simples, mas que facilitam na manutenção.

Umas das coisas que aprendi com Uncle Bob (Robert C. Martin), no seu livro Clean Code foi: escrevemos o código apenas uma vez, porém o mesmo é lido várias vezes. Então, não custa usarmos 5min a mais documentando alguma coisa ou escrevendo variáveis legíveis, que nos pouparão tempo mais tarde!

1. Clareza e objetivadade nos nomes das variáveis

É incrível como as pessoas conseguem dar nomes criativos para variáveis. O alfabeto tem tantas letras que formam tantas palavras, por que insistem em usar apenas 1 letra como nome de variável? Pior, Por que usar sempre as mesmas?

$d = 3;
$dias = 2;

A primeira variável simplesmente não diz nada. Olhando ela não se consegue ter noção nenhuma do que ela representa, o que é o 3? Do mesmo modo se aplica a segunda variável, sabemos que são 2 dias, mas 2 dias não nos diz nada também. Olhando assim, só sabemos a unidade de medida!

$dia_vencimento = 3;
$qtde_dias_para_pagamento  = 2;

Há quem reclame do tamanho das variáveis. Mas hoje em dia, que editor não auto-completa para você? Se o seu não, por favor, considere trocar =).

O que se deve cuidar ao se nomear uma variável, é não por algum nome que venha a ter mais de uma possibilidade de significado. Por exemplo:

$valor_frete_desconto = 11.3;

O valor acima citado, é referente ao desconto dado ao frete, ao valor do frete a ser descontado ou o valor do frete com o desconto? Eu não afirmo nenhuma hipótese à partir do nome dado. Se me perguntarem, eu diria que olharia o código para afirmar. Por tanto, seja CLARO E OBJETIVO.

$valor_frete = 13.4;
$valor_desconto_frete = 2.3;
$valor_frete_descontado = $valor_frete - $valor_desconto_frete;

Caso o desconto do frete seja aplicado com porcentagem:

$pct_desconto_frete = 10;
$valor_frete = 13.4;
$valor_desconto_frete = $valor_frete * ($pct_desconto_frete / 100);
$valor_frete_descontado = $valor_frete - $valor_desconto_frete;

A melhor coisa em relação às variáveis é justamente o fato de omitir o valor atrás de um nome inteligível. Por tanto, sempre que possível, esconda os valores, a legibilidade aumenta muito!

    $arr_usrs = array();
    for ($i = 0; $i < count($users); $i++) {
        if ($users[$i][3] == 4)
            $arr_usrs[] = $users[$i];
    }
    return $arr_usrs;
}

Pergunto:

• $arr_usrs é uma lista gerada à partir de que dados?
• O que é o índice 3 do array usado no if ?
• O que diabos quer dizer == 4?
• O que devo esperar que $arr_usrs contenha?

define("STATUS", 3);
define("ATIVO", 4);
    $contatosAtivos = Array();
    for ($i = 0; $i < count($contatos_do_usuario); $i++) {
        $contato = $contatos_do_usuario[$i];
        $status_do_contato = $contato[STATUS];
        if ($status_do_contato == ATIVO)
            $contatosAtivos[] = $contato;
    }
    return $contatosAtivos;

Acho que não preciso explicar o código, não é?

Outra coisa interessante, CUIDADO com as variáveis de duplo sentido.

$total = count($usuariosDoBanco);

$total recebeu o total de usuários do Banco de Dados ? o total de usuários de um determinado banco (BB, Santander, etc) ?

Sugestão:

$total = count($usuarios_cadastrados);

ou, para o outro caso

$total = count($clientes_santander);

Eu sei que muitas vezes é difícil escrever códigos de forma bonita, mas o esforço vale a pena! Além de ser um diferencial profissional, trabalhar no meio da zona é prejudicial a você mesmo!

Lembrou de algo? Tens outras dicas? Comenta aê!