Boas Práticas de Nomenclatura em Java

Nomes são a documentação mais barata que você jamais escreverá e a mais cara de acertar. Java possui um conjunto forte e quase universal de convenções de nomenclatura — codificado na Java Language Specification original e reforçado pelo JDK, por todas as principais bibliotecas e por ferramentas como o Checkstyle. Segui-las não é uma questão de gosto: permite que qualquer leitor Java infira o que uma coisa é pela maneira como está escrita, antes de ler uma única linha do seu corpo. Este capítulo reúne as regras de nomenclatura que importam e as demonstra em uso; para espaçamento, posicionamento de chaves e organização de arquivos, veja convenções de codificação Java.

As convenções de caixa em resumo

Java atribui um estilo de caixa distinto a cada tipo de identificador. A caixa por si só indica ao leitor a categoria:

package com.w3docs.billing;          // lowercase, reverse-domain

public class InvoiceService {        // PascalCase class
  private static final int MAX_RETRY_COUNT = 3;  // UPPER_SNAKE_CASE constant
  private final TaxTable taxTable;   // camelCase field

  public BigDecimal calculateTotal(List<LineItem> lineItems) { ... } // camelCase method
}

Pacotes: minúsculos e domínio invertido

Os nomes de pacotes são sempre minúsculos, sem underscores, e começam a partir de um domínio que você controla invertido — com.w3docs.billing, não Billing ou w3docs_billing. O prefixo de domínio invertido mantém seus pacotes globalmente únicos, para que nunca colidam com uma biblioteca de terceiros no classpath. Evite palavras-chave Java e dígitos como o primeiro caractere de qualquer segmento. Veja criação de pacotes para o layout de diretórios que esses nomes implicam.

package com.w3docs.billing.tax;   // good: lowercase, reverse-domain, dotted
// package Com.W3docs.Billing;    // bad: uppercase segments
// package com.w3docs.2024billing;// bad: segment starts with a digit

Classes são substantivos, métodos são verbos

Uma classe, interface, enum ou record modela uma coisa, portanto seu nome é uma frase substantiva em PascalCase: Order, PaymentGateway, OrderLine. Um método faz algo, portanto seu nome é uma frase verbal em camelCase: calculateTotal, sendInvoice, parseDate. Duas sub-convenções importantes decorrem disso:

• Métodos que retornam um boolean leem como uma pergunta: isEmpty, hasNext, canRetry.
• Os acessores clássicos usam o prefixo get/set (getName, setName) — mas os records Java geram acessores nomeados após o campo sem prefixo (name(), não getName()).

interface PaymentGateway {          // noun, PascalCase
  boolean isAvailable();            // boolean → question form
  Receipt charge(Money amount);     // verb phrase
}

record Customer(String name, String email) { }  // accessors: name(), email()

Constantes, variáveis e parâmetros de tipo

Uma constante static final cujo valor é fixado em tempo de compilação usa UPPER_SNAKE_CASE para se destacar das variáveis comuns: MAX_RETRY_COUNT, DEFAULT_TAX_RATE. Variáveis locais, parâmetros e campos são substantivos em camelCase que descrevem o valor, não seu tipo — prefira taxRate a d ou theDouble. Os parâmetros de tipo genérico são letras maiúsculas únicas por convenção histórica:

static final double DEFAULT_TAX_RATE = 0.20;        // constant
public <K, V> Map<K, V> copyOf(Map<K, V> source) { ... } // type params K, V

Evite estes erros comuns

Alguns antipadrões aparecem repetidamente. Eles compilam, mas dificultam a leitura:

• Nomes húngaros / codificados por tipo — strName, iCount, lstOrders. O tipo já está na declaração; o nome deve descrever o significado.
• Variáveis de uma única letra além de contadores de loop — c, x, tmp para um valor de domínio escondem a intenção.
• Abreviações crípticas — calcGrsTtl. Escreva as palavras por extenso; as IDEs modernas fazem autocompletar.
• l (L minúsculo) e O como nomes de variáveis — eles são visualmente indistinguíveis de 1 e 0.
• Nomes de classe que são verbos (ProcessData) ou nomes de método que são substantivos — prefira order.calculateTotal() para algo que calcula, reservando a forma substantiva pura para acessores.

Um exemplo completo: as convenções em um único programa

Este programa aplica todas as regras acima em um único arquivo — uma constante, um record com acessores sem prefixo, um método de consulta boolean, um método camelCase com parâmetros descritivos e uma lista genérica. Leia o código-fonte e a saída juntos para ver como a caixa se mapeia à categoria.

O que observar na execução:

• As duas constantes UPPER_SNAKE_CASE são impressas como max retry count : 3 e default tax rate: 0.2 — sua caixa sinaliza no ponto de uso que são valores fixos e compartilhados, não locais que podem ser reatribuídos.
• OrderLine é um record em PascalCase, e o loop lê seus dados através de productName(), quantity() e lineTotal() — note que não há prefixo get, pois os acessores de record são nomeados exatamente após o componente.
• isBulk() imprime bulk=true para a linha com 12 unidades e bulk=false para a de 1 unidade: o prefixo is indicou que retornava um boolean antes mesmo de ler o corpo, e a saída confirma que a convenção se justifica no ponto de chamada.
• calculateGrossTotal é um método de frase verbal cujos parâmetros orderLines e taxRate descrevem o significado, não o tipo — o resultado gross total : 111.60 (93.00 líquido vezes 1.20) é exatamente o que o nome do método prometeu.
• A linha final usa List<String>, um genérico parametrizado com um tipo concreto, ecoando a convenção de parâmetro de tipo (E para elemento) com que as coleções JDK são declaradas — o programa imprime [alpha, beta] para mostrar a lista tipada em ação.

Prática