Nomear Coisas no Código O Guia Prático Que Vai Salvar Sua Sanidade

Por Que Nomear É o Problema Mais Difícil do Software

Tem uma piada clássica: os dois problemas mais difíceis da computação são invalidação de cache, nomear coisas e erros de off-by-one. Mas nomear não é só piada — é um atrito diário que drena silenciosamente a produtividade do time.

Quando o designer chama de "card", o PM chama de "tile" e o código chama de BoxContainer, você já perdeu. A linguagem que usamos molda como pensamos sobre o sistema, e nomes inconsistentes criam fragmentação de dialetos entre papéis.

Este guia quebra abordagens comprovadas para nomear o que devs realmente nomeiam todo dia: design tokens, componentes de UI, classes CSS, features e variáveis. Cada seção aponta para um recurso concreto e testado que você pode salvar e usar imediatamente.

TL;DR: Bons nomes são curtos, lógicos, significativos, conhecidos por todos e não ligados a propriedades visuais. Nomes ruins são ou muito genéricos (container) ou muito específicos (blueButtonLarge).

Vamos ao playbook prático. 🚀

Nomeando Design Tokens: Aprenda com a Taxonomia da Intuit

Design tokens é onde o caos da nomenclatura bate mais forte — porque cruza a fronteira designer-dev. A Intuit (dona do Mailchimp, QuickBooks e TurboTax) construiu uma taxonomia flexível de tokens que escala entre múltiplas marcas e produtos.

O Princípio Central: Separe Responsabilidades por Camada

Um sistema de tokens robusto geralmente tem quatro camadas:

Primitives  →  Semantics  →  Components  →  Pages
(valores)      (intenção)    (contexto)     (uso)

• Primitives: blue-500, space-4, radius-md — valores brutos, sem marca
• Semantics: color-action-primary, space-inline-sm — baseados em intenção
• Components: button-bg-hover, card-padding — escopo do componente
• Pages: checkout-header-bg — overrides por página (use com moderação)

O Variables Taxonomy Map da Vodafone UK

O time de design system da Vodafone UK publicou um Variables Taxonomy Map que visualiza como os tokens se conectam entre essas quatro coleções. O insight-chave: só pelo nome de um token, qualquer dev deve inferir onde ele é usado e o que ele representa.

brand.color.primary
  └── primitives.color.blue.500
        └── semantics.color.action.primary
              └── components.button.background

Se você consegue ler essa cadeia e entender a intenção na hora, sua taxonomia está funcionando.

Ferramenta: Design Token Naming Guide

Romina Kavcic criou um guia + inventário de nomes que te ajuda a configurar sua própria estrutura com componentes, categorias, estados e papéis. A planilha companheira te dá uma visão geral de cada token, filtrável por tema e modo.

Dica de pro: Antes de inventar sua taxonomia, confere o trabalho fundamental do Nathan Curtis sobre naming de design tokens — a maioria dos sistemas modernos é construída em cima dele.

Nomeando Componentes de UI, Cores e Features

Componentes de UI: Compare Antes de Decidir

Travado pra nomear um componente? Não invente — compare. A Component Gallery do Iain Bean cataloga mais de 50 componentes de UI (de accordion a visually-hidden) e lista os nomes alternativos que cada um recebe nos principais design systems.

Isso resolve o problema clássico: é Toast, Snackbar, Notification ou Alert? A galeria te mostra como Material, Carbon, Polaris e outros chamam — aí você escolhe o termo mais amplamente entendido.

Pra nomes específicos de comportamento, o namethatui.com é um dicionário visual de padrões comuns de UI.

Cores: Mais de 30 Mil Nomes na Sua Mão

David Aerne mantém um repositório com 30.355 nomes únicos de cores — vindos de referências e milhares de contribuições da comunidade. Vem com color picker e busca por nome. Quando #FF6B6B precisa de um nome humano, é aí que você olha.

Features: Nomeie com a Boca do Usuário, Não do Roadmap

Adoção de feature falha quando a descoberta falha. O guia prático da Erin Gannon deixa um ponto cristalino: bons nomes de feature usam a linguagem do próprio usuário, não jargão interno.

A técnica:

1. Peça pra 5 usuários explicarem a feature com as próprias palavras
2. Extraia os substantivos e verbos recorrentes
3. Use essas palavras como nome da feature

Aviso: Não nomeie features com nomes de time interno, codinomes de sprint ou abstrações de engenharia. O usuário não liga que internamente chama "Projeto Falcão".

Layers e Grupos: Consistência Acima de Criatividade

As boas práticas de nomenclatura do Javier Cuello pra layers e grupos no Figma se resumem a cinco regras:

Variáveis: O Naming Cheatsheet

Pra variáveis no nível de código, o naming-cheatsheet no GitHub é a referência de fato. A fórmula central:

[ação][contexto][alvo]

Exemplos:

• getUserProfile (ação: get, contexto: User, alvo: Profile)
• isEmailValid (prefixo booleano + sujeito)
• handleSubmitClick (padrão de event handler)

Anti-padrão: data, info, temp, value, obj — isso não são nomes, são placeholders fingindo ser nomes.

A Conclusão: Nomes São um Contrato de Time

O nome certo é aquele que é bem entendido e usado pelo time e pelos usuários. Todo o resto é ruído.

Quando a adoção tá baixa, antes de culpar a feature, o onboarding ou a documentação — cheque o nome. Um nome confuso é um imposto pago em toda conversa, todo code review e todo ticket de suporte.

Referência Rápida: Salva Aí

• Classes: classnames.paulrobertlloyd.com
• Cores: parrot.color.pizza
• Design tokens: taxonomia da Intuit + mapa da Vodafone UK
• Features: guia de naming do Shopify Polaris
• Componentes de UI: component.gallery
• Comportamento de UI: namethatui.com
• Variáveis: naming-cheatsheet
• Produtos: guide.onym.co

O Que Fazer Agora

1. Audite seus nomes atuais. Roda um grep rápido por data, temp, box, container no codebase. Cada hit é um futuro ponto de confusão.
2. Escolha uma camada de taxonomia (ex: design tokens) e padronize ela neste sprint. Não tente ferver o oceano.
3. Coloque conflitos de nome no backlog — não conserte tudo de uma vez, mas também não esqueça.

Pra entender como nomenclatura molda arquitetura de sistemas, dá uma olhada na nossa análise sobre construir um flywheel de ASR clínico com skills de agentes de IA — onde nomenclatura consistente entre pipelines de IA fez a diferença entre um sistema mantenível e um pesadelo de debug. E se você acompanha como nomenclatura de infraestrutura escala em datacenters da era da IA, nosso breakdown da integração do Azure com a plataforma NVIDIA Rubin mostra por que convenções de nome importam em todas as camadas da stack.

Fonte: Este guia é baseado no artigo da Smashing Magazine How To Name Things, reorganizado para uso prático focado em devs.

Nomear é esporte coletivo. A melhor hora de consertar foi no início do projeto. A segunda melhor é agora. 💪