code-styledocs

Naming

Nomear bem as coisas ajuda o programador a ler e entender o código. Um identificador expressivo elimina comentários, encurta a leitura e revela intenção.

Um nome genérico (data, result, tmp) força o programador a abrir o corpo da função pra entender o que está acontecendo. Em funções e módulos, o nome ainda compõe a API (Application Programming Interface, Interface de Programação) que outro código vai consumir. Errar ali custa mais caro.

Quando o nome carrega a intenção, o comentário deixa de fazer falta.

Conceitos fundamentais
ConceitoO 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, 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çãoPreferirEvitar
Ler de storagefetch, load, find, getretrieve, pull
Escrever/persistirsave, persist, create, insertput, push
Calcular/derivarcompute, calculate, derive, buildget, do
Transformarmap, transform, convert, formatprocess, parse
Validarvalidate, check, assert, verifyhandle, test
Notificarsend, dispatch, notify, emitfire, trigger

Domain-first naming

O nome reflete a intenção de negócio, não o detalhe técnico de como ou onde a operação acontece.

❌ 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

Comentários que explicam o quê mentem: o código muda, o comentário fica. Um nome expressivo substitui qualquer comentário.

❌ 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++;

Boolean naming
❌ 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;

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.