Já participei de conversas em que todo mundo concordava com a palavra “pagamento”, mas cada pessoa estava pensando em um momento diferente: intenção criada, cobrança autorizada, dinheiro confirmado ou repasse concluído. O problema só aparecia quando o código “correto” produzia o comportamento errado.
Linguagem Ubíqua serve para diminuir esse tipo de tradução silenciosa. Não é pedir que negócio aprenda nomes de classes. É construir, em conjunto, palavras precisas o bastante para orientar conversa, regra, teste e implementação.
Glossário ajuda, uso diário resolve
Uma página com definições pode virar arquivo morto em duas semanas. A linguagem ganha força quando aparece nos critérios de aceite, endpoints, eventos, mensagens de erro e nomes do código. Se produto diz “agendamento” e a aplicação chama tudo de record, alguém continuará traduzindo mentalmente.
Prefiro registrar exemplos: quando o conceito nasce, quem pode alterá-lo e quais situações ficam de fora. É difícil esconder uma discordância diante de um caso concreto.
Palavras têm endereço
Não precisamos eleger um significado universal. “Atendimento” em um contexto clínico e em uma central de suporte pode ser legitimamente diferente. A saída não é criar um objeto gigante que acomode ambos, mas dizer em qual contexto cada definição vale.
- Termo: o nome usado dentro daquela fronteira.
- Exemplo: uma situação real que testa o entendimento.
- Regra: o que precisa continuar verdadeiro.
- Tradução: a conversão explícita ao cruzar contextos.
Nomes mudam o desenho
updateStatus aceita quase qualquer coisa e conta muito pouco. confirmarPagamento expõe uma intenção e convida perguntas melhores: pode confirmar duas vezes? Quem confirma? O que ocorre depois? Um nome específico frequentemente revela a API que estava faltando.
Também funciona ao contrário. Quando uma flag booleana precisa de um parágrafo para ser entendida, provavelmente há um conceito escondido ali.
Onde isso ficou evidente
Na KasbHealth, diferenciar linguagem clínica de linguagem operacional evita que regras sensíveis sejam tratadas como detalhes de tela. Em integrações com Stripe feitas em trabalhos com Sinaxys e Entrega Contínua, mapear termos externos para conceitos internos impediu que o modelo do provedor comandasse o produto.
Essas traduções são código de negócio. Vale nomeá-las, testá-las e revisá-las como tal.
Um nome preciso não é preciosismo. É uma decisão de arquitetura em uma escala que usamos todos os dias.
Como manter a linguagem viva
Reviso nomes em refinamentos e pull requests, sobretudo quando surge uma exceção nova. Testes baseados em comportamento são bons aliados porque denunciam quando o texto conta uma história e a implementação conta outra.
Renomear custa uma vez. Conviver com duas interpretações custa em toda conversa, correção e nova feature.
Conclusão
Linguagem Ubíqua não elimina divergências; ela as traz para a mesa enquanto ainda são baratas de resolver. Quando os mesmos conceitos atravessam produto, testes e código sem perder o sentido, a equipe trabalha com menos adivinhação — e percebe mais cedo quando o próprio entendimento precisa mudar.