Nomes honestos

A redefinição: um nome não é rótulo, é contrato com o leitor. Ele diz a verdade sobre a consequência. É a tese do Makoto (誠, “sinceridade/verdade”) encarnada na superfície da API.

O conceito

Nomes de API costumam otimizar para brevidade ou para jargão de comunidade: unwrap, is_some, upsert, try. São curtos e familiares, mas escondem o que custam: unwrap não diz que crasha, try não diz se devolve Result ou Optional ou se panica. O leitor precisa lembrar a semântica de fora do nome.

Como Makoto redefine

Os nomes são escolhidos para mostrar a consequência no próprio nome:

• or_panic, não unwrap: o nome diz o que acontece se vazio, ou seja, panica. A consequência está à vista, não escondida atrás de uma metáfora (“desembrulhar”).
• is_present, não is_some: “presente” é legível e descreve o fato (a coisa existe), em vez de ecoar o Some do enum de outra linguagem.
• as_string_unchecked: o _unchecked é obrigatório, porque você está pulando a validação; um as_string mudo seria uma silhueta mentirosa.
• update_or_insert, não upsert: a ação (“tenta atualizar, senão insere”) em vez do jargão de banco de dados.

E o mesmo princípio governa as marcas da linguagem (cap. 01): @mm(none) diz “você é responsável” e @mm(gc) diz “o sistema cuida”; unsafe { } marca onde as promessas estão suspensas; pub expõe e o privado é pelado. Nenhuma promessa invisível.

O raciocínio

Código é lido ordens de magnitude mais vezes do que é escrito. Economizar três caracteres no nome (uwrap, upd) e custar trinta de compreensão a cada leitura é um péssimo negócio. Mas o argumento mais profundo é que nome honesto é o teste do opt-in aplicado ao vocabulário: um nome que esconde a consequência faz você pagar (em surpresa) por algo que não convocou conscientemente. or_panic te deixa convocar o panic de olhos abertos; unwrap te deixa convocá-lo sem perceber.

Por isso este não é um capítulo “de estilo”; é a tese da linguagem na superfície. Makoto significa “verdade/sinceridade”, e a recusa de vazar cores entre subsistemas (cap. 00) tem um irmão na API: a recusa de esconder consequências atrás de nomes confortáveis. O mesmo espírito aparece em decisões finas: resize devolve um bool (coube in-place?) em vez de um ponteiro à realloc, porque o realloc clássico esconde uma cópia+free atrás de uma chamada que parece barata. Separar é mais honesto.

Por que não as alternativas

• unwrap/is_some (Rust). unwrap é tão comum que o programador esquece que é um crash, e o acumula em código que deveria ser robusto. O nome anestesia a consequência; or_panic a mantém acordada.
• Siglas e jargão (upsert, uwrap). Economizam digitação e custam compreensão; jargão exige que o leitor conheça o dialeto. update_or_insert é auto-descritivo.
• Nomes genéricos (try, get sem qualificação). try não diz a forma do retorno nem o comportamento de falha; é vago. O nome honesto é específico sobre a consequência.
• Convenção em vez de nome/marca (capitalização = público, à la Go). Depende de atenção, quebra com um typo, e fica escondida no token. A marca explícita (pub) não.

A dor concreta

O unwrap() espalhado por uma base Rust “só para o protótipo” que vira o ponto de crash em produção, porque o nome nunca lembrou ninguém de que era um abismo. O upsert que um dev novo precisa ir pesquisar. O as_string que silenciosamente aceitou bytes inválidos porque não havia um _unchecked para fazer soar o alarme. Cada uma é um nome que mentiu por omissão.

O modelo mental

O nome diz a verdade sobre a consequência. Se uma operação pode crashar, pular validação ou custar caro, o nome (ou a marca) avisa, antes de você apertar o gatilho.

A fricção aceita

Nomes honestos são mais longos, e você precisa aprender os “nomes reais” em vez dos jargões que já conhece de outras linguagens (or_panic em vez do reflexo unwrap). É uma curva de hábito real. A aposta: a verdade dita uma vez no nome se paga em cada uma das milhares de leituras seguintes, e é, afinal, o que o nome da linguagem promete.

Próximo: 13 · Verificação