Nomes que explicam sozinhos

O nome é o comentário mais lido

De todos os hábitos de código limpo, nomear bem é o que mais rende, e o mais barato. A razão é simples: o nome de uma variável ou função aparece em cada linha que a usa, então é o texto que mais se lê num programa. Um nome bem escolhido conta a história sozinho. Quando você lê preco_com_desconto ou calcular_frete, entende na hora do que se trata, sem precisar caçar a definição nem ler um comentário. Já um nome ruim, como x, temp, valor2 ou func, esconde a intenção e obriga quem lê a investigar: o que é esse x? de onde vem esse valor2? Cada nome preguiçoso é um pequeno pedágio que quem lê paga, e o principal pagador é você mesmo, daqui a alguns meses, tentando entender o próprio código.

Um bom nome descreve o que a coisa representa, não como ela é feita. Para uma variável, um substantivo claro: idade, total_carrinho, lista_aprovados. Para uma função, muitas vezes um verbo que diz a ação: calcular_media, validar_email, buscar_cliente. O nome deve ser específico o bastante para não confundir: dados é vago demais, dados_do_cliente já ajuda, cadastro_cliente é ainda melhor. Não tenha medo de nomes um pouco mais longos se eles forem mais claros; um nome de três palavras que se explica vence uma abreviação de três letras que ninguém decifra. A única economia que vale em nome é cortar o que não agrega, não o que esclarece.

O pior nome é o que engana

Se o nome genérico é ruim, o nome enganoso é pior ainda. Uma variável chamada lista que na verdade guarda um único valor, uma função chamada salvar que só valida sem salvar, um total que é na verdade uma média: esses nomes mentem, e um nome que mente é mais perigoso que a ausência de nome, porque induz quem lê a conclusões erradas. Quem confia no nome salvar vai supor que os dados foram guardados, e o bug nasce dessa suposição. Por isso, ao renomear ou reaproveitar código, tome cuidado para o nome continuar honesto: se o que a variável guarda mudou, o nome tem que mudar junto. Um nome desatualizado é uma armadilha esperando quem passar. A regra de ouro é: o nome deve dizer a verdade sobre o que a coisa é hoje, não o que ela foi um dia.

O custo de nomear mal se acumula

Pode parecer exagero dedicar tanta atenção a nomes, mas o custo de nomear mal se acumula de um jeito silencioso. Cada nome ruim isoladamente custa só alguns segundos de confusão. Mas um programa tem centenas de nomes, lidos milhares de vezes ao longo da sua vida, por várias pessoas, incluindo o próprio autor voltando meses depois. Multiplique os segundos de confusão pela quantidade de leituras e você tem horas de tempo desperdiçado, além de bugs que nascem de mal-entendidos. Nomear bem, por outro lado, custa só um instante de reflexão na hora de escrever, e paga dividendos para sempre. É por isso que programadores experientes gastam um tempo aparentemente desproporcional escolhendo nomes: eles sabem que estão investindo na legibilidade de tudo que virá depois. Um código com bons nomes muitas vezes dispensa comentários, porque ele já se explica linha a linha.