Naming

Nomear bem é o que faz outra pessoa (ou você mesmo daqui a três meses) ler o código e entender na hora. Um nome expressivo mostra a intenção, encurta a leitura e dispensa comentário. Um nome genérico (data, result, tmp) faz o contrário: obriga o leitor a abrir o corpo da função para descobrir o que acontece ali. Em funções e módulos o erro custa ainda mais caro, porque o nome vira parte da API (Application Programming Interface · Interface de Programação de Aplicações), o contrato que outro código vai usar.

Conceitos fundamentais

Conceito	O que é
identifier (identificador)	Nome dado a variável, função, classe ou propriedade
camelCase (estilo camelo)	Convenção JS para variáveis e funções: primeira palavra minúscula, demais capitalizadas (`fetchUser`)
PascalCase (estilo Pascal)	Convenção JS para classes e construtores: todas as palavras capitalizadas (`UserService`)
UPPER_SNAKE_CASE (maiúsculas com sublinhado)	Convenção JS para constantes globais e enums (`MAX_RETRIES`)
magic number (número mágico)	Literal numérico sem nome no meio do código; perde contexto e dificulta troca
boolean prefix (prefixo booleano)	`is`, `has`, `can`, `should`: torna o nome legível como pergunta (`isActive`, `hasPermission`)
domain term (termo de domínio)	Palavra que pertence ao negócio (`invoice`, `subscriber`), não ao tipo técnico (`object`, `entity`)

Identificadores sem significado

❌ Ruim

const r = apply(data, pedido, callback);

function apply(x, p, c) {
  if (p.c.inadimplente) return false;
  return c(x);
}

✅ Bom

const discountedOrder = applyDiscount(order, calculateDiscount);

function applyDiscount(order, calculateDiscount) {
  if (order.customer.defaulted) return null;

  const discountedOrder = calculateDiscount(order);
  return discountedOrder;
}

Nomes em português

❌ Ruim: camelCase com português fica desajeitado

const nomeDoUsuario = "Alice";
const listaDeIds = [1, 2, 3];

function retornaOUsuario(id) {
  /* ... */
}
function buscaEnderecoDoCliente(id) {
  /* ... */
}

✅ Bom: inglês é curto, direto e universal

const userName = "Alice";
const idList = [1, 2, 3];

function getUser(id) {
  /* ... */
}
function getCustomerAddress(id) {
  /* ... */
}

Mistura de idiomas

❌ Ruim: português e inglês no mesmo arquivo

function notify(pedido) {
  console.log("cliente inadimplente", pedido?.cliente?.nome);
}

const resultado = processOrder(pedido);

✅ Bom: consistência de idioma

function notifyDefault(order) {
  console.log("defaulted customer:", order?.customer?.name);
}

const result = processOrder(order);

Ordem semântica invertida

Em inglês, o nome segue a ordem natural da fala: ação + objeto + contexto.

❌ Ruim: ordem invertida

getProfileUser(); // "get profile, that's a user"
updateStatusOrder(); // status pertence ao pedido

calculateTotalInvoice(); // "invoice total" é a expressão natural

✅ Bom: ordem natural

getUserProfile();
updateOrderStatus();

calculateInvoiceTotal();

Verbos genéricos

❌ Ruim: handle, process, manage, do não dizem nada

function handle(data) {
  /* ... */
}
function process(input) {
  /* ... */
}

function manage(items) {
  /* ... */
}
function doStuff(x) {
  /* ... */
}

✅ Bom: verbo de intenção

function validatePayment(payment) {
  /* ... */
}
function calculateOrderTotal(items) {
  /* ... */
}

function notifyCustomerDefault(order) {
  /* ... */
}
function applySeasonalDiscount(order) {
  /* ... */
}

Taxonomia de verbos

Intenção	Preferir	Evitar
Ler de storage	`fetch`, `load`, `find`, `get`	`retrieve`, `pull`
Escrever/persistir	`save`, `persist`, `create`, `insert`	`put`, `push`
Calcular/derivar	`compute`, `calculate`, `derive`, `build`	`get`, `do`
Transformar	`map`, `transform`, `convert`, `format`	`process`, `parse`
Validar	`validate`, `check`, `assert`, `verify`	`handle`, `test`
Notificar	`send`, `dispatch`, `notify`, `emit`	`fire`, `trigger`

Nome pelo domínio, não pela infraestrutura

O nome mostra a intenção de negócio, não o detalhe técnico de onde ou como a operação acontece. chargeCustomer diz o que importa; callStripe prende o nome à ferramenta do momento, que amanhã pode mudar.

❌ Ruim: nome revela infraestrutura, não domínio

function callStripe(amount) {
  /* ... */
}
function getUserFromDB(id) {
  /* ... */
}

function postToSlack(message) {
  /* ... */
}
function saveToS3(file) {
  /* ... */
}

function queryElastic(term) {
  /* ... */
}

✅ Bom: nome fala a linguagem do negócio

function chargeCustomer(amount) {
  /* ... */
}
function findUser(id) {
  /* ... */
}

function notifyTeam(message) {
  /* ... */
}
function archiveDocument(file) {
  /* ... */
}

function searchProducts(term) {
  /* ... */
}

Código como documentação

Um comentário que explica o quê o código faz envelhece mal: o código muda, o comentário fica para trás e passa a mentir. Um nome expressivo dispensa o comentário e nunca sai de sincronia com o código.

❌ Ruim: comentário repete o que o código já diz

// verifica se o usuário pode excluir registros
if (user.status === "active" && user.roles.includes("admin")) {
  deleteRecord(id);
}

// incrementa tentativas
attempts++;

✅ Bom: nome expressivo torna o comentário desnecessário

const canDeleteRecord =
  user.status === "active" && user.roles.includes("admin");
if (canDeleteRecord) {
  deleteRecord(id);
}

attempts++;

Nomes de booleano

❌ Ruim: booleanos sem prefixo semântico

const loading = true;
const error = false;

const active = user.status === "active";
const valid = email.includes("@");

✅ Bom: prefixos is, has, can, should

const isActive = user.status === "active";
const hasPermission = user.roles.includes("admin");

const canDelete = isActive && hasPermission;
const shouldRetry = attempt < MAX_RETRIES;

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.