Nomear identificadores: pelo papel, no vocabulário do domínio, com comprimento proporcional ao escopo

Objetivo

Quem lê entende a função ou a variável pelo nome, sem precisar ler o corpo, e uma busca por um conceito encontra exatamente os usos dele.

Pré-requisitos

Um vocabulário comum do domínio (glossário no README ou nos registros de decisões); uma ferramenta que renomeie com segurança em todo o projeto; a convenção de nomes da linguagem como regra estabelecida: PEP 8 para Python, «Effective Go» para Go.

Passos

1. Nomeie pelo papel e pelo significado, não pelo tipo ou pelo mecanismo: mahnfrist em vez de dt2, offene_rechnungen em vez de liste1, nach_kundin_gruppiert em vez de dict_result.
2. Ajuste o comprimento ao escopo: um índice de laço pode se chamar i, mas uma constante de módulo ou uma função pública precisa de uma descrição completa. O Effective Go observa que nomes longos não tornam o código automaticamente mais legível e que um bom comentário de documentação costuma valer mais do que um nome muito longo.
3. Use uma palavra por conceito em todo o projeto: laden, holen ou lesen, não os três ao mesmo tempo; use os termos do domínio, não os do framework.
4. Nomeie booleanos como afirmações (ist_abgelaufen, hat_kinder), funções como verbo ou locução verbal (berechne_total, sende_erinnerung) e coleções no plural; coloque as unidades no nome quando o tipo não as expressa (timeout_ms, betrag_rappen).
5. Evite codificações: sem prefixos de tipo e sem sufixos como _v2 ou _neu, que passam a mentir após a próxima alteração. O PEP 8 proíbe os caracteres isolados l, O e I como nomes de variáveis, porque em algumas fontes não se distinguem de 1 e 0.
6. Respeite as convenções da linguagem para visibilidade e forma: em Go, a letra maiúscula inicial determina a exportação, e interfaces com um único método terminam por convenção em -er (Reader, Writer); em Python, sublinhados separam palavras e um sublinhado inicial marca o que é interno.
7. Se um nome precisa de um comentário para ser entendido, renomeie em vez de comentar. Quando surgir uma compreensão melhor, renomeie imediatamente, com ferramenta e em um commit próprio, sem outras mudanças.

Resultado esperado

Menos comentários, revisões mais curtas, buscas que encontram exatamente os usos de um conceito e código no qual especialistas do domínio reconhecem os seus termos.

Limites e base de verificação

Nomes de API pública não podem ser alterados livremente; por isso merecem mais cuidado na primeira vez. Usar identificadores em alemão ou em inglês é uma decisão da equipe, que precisa valer de forma consistente; formas mistas (getKundin) são o pior dos dois mundos. As convenções vêm das diretrizes de estilo citadas; não se afirma nenhuma medição.