Honest names

The redefinition: a name is not a label, it is a contract with the reader. It tells the truth about the consequence. It is Makoto’s thesis (誠, “sincerity/truth”) incarnate on the surface of the API.

The idea

API names usually optimize for brevity or for community jargon: unwrap, is_some, upsert, try. They are short and familiar, but they hide what they cost: unwrap does not say that it crashes, try does not say whether it returns Result or Optional or whether it panics. The reader has to remember the semantics from outside the name.

How Makoto redefines it

The names are chosen to show the consequence in the name itself:

• or_panic, not unwrap: the name says what happens if empty, that is, it panics. The consequence is in view, not hidden behind a metaphor (“unwrapping”).
• is_present, not is_some: “present” is readable and describes the fact (the thing exists), instead of echoing the Some of another language’s enum.
• as_string_unchecked: the _unchecked is mandatory, because you are skipping the validation; a mute as_string would be a lying silhouette.
• update_or_insert, not upsert: the action (“try to update, otherwise insert”) instead of the database jargon.

And the same principle governs the language’s marks (ch. 01): @mm(none) says “you are responsible” and @mm(gc) says “the system takes care”; unsafe { } marks where the promises are suspended; pub exposes and the private is bare. No invisible promise.

The reasoning

Code is read orders of magnitude more times than it is written. Saving three characters in the name (uwrap, upd) and costing thirty of comprehension on every read is a terrible deal. But the deeper argument is that an honest name is the opt-in test applied to vocabulary: a name that hides the consequence makes you pay (in surprise) for something you did not consciously summon. or_panic lets you summon the panic with open eyes; unwrap lets you summon it without noticing.

That is why this is not a “style” chapter; it is the language’s thesis on the surface. Makoto means “truth/sincerity”, and the refusal to leak colors between subsystems (ch. 00) has a sibling in the API: the refusal to hide consequences behind comfortable names. The same spirit appears in fine decisions: resize returns a bool (did it fit in-place?) instead of a pointer à la realloc, because the classic realloc hides a copy+free behind a call that looks cheap. Separating is more honest.

Why not the alternatives

• unwrap/is_some (Rust). unwrap is so common that the programmer forgets it is a crash, and accumulates it in code that should be robust. The name anesthetizes the consequence; or_panic keeps it awake.
• Acronyms and jargon (upsert, uwrap). They save typing and cost comprehension; jargon requires the reader to know the dialect. update_or_insert is self-describing.
• Generic names (try, get without qualification). try does not say the shape of the return nor the failure behavior; it is vague. The honest name is specific about the consequence.
• Convention instead of a name/mark (capitalization = public, à la Go). It depends on attention, breaks with a typo, and stays hidden in the token. The explicit mark (pub) does not.

The concrete pain

The unwrap() scattered across a Rust codebase “just for the prototype” that becomes the crash point in production, because the name never reminded anyone that it was an abyss. The upsert that a new dev has to go look up. The as_string that silently accepted invalid bytes because there was no _unchecked to sound the alarm. Each one is a name that lied by omission.

The mental model

The name tells the truth about the consequence. If an operation can crash, skip validation or cost a lot, the name (or the mark) warns you, before you pull the trigger.

The accepted friction

Honest names are longer, and you have to learn the “real names” instead of the jargon you already know from other languages (or_panic instead of the reflex unwrap). It is a real habit curve. The bet: the truth said once in the name pays off in each of the thousands of reads that follow, and it is, after all, what the language’s name promises.

Next: 13 · Verification