Case file F2

Intention-Revealing Names

The signature is the spec.

A reader who sees only the function name and its parameters should know what the call does. If the name does not take that load, the code has not finished saying it yet. Rename, split per F1 Single Responsibility, or introduce a type per T1 Domain-Driven Types.

ByAdam LewisPublished28 Apr 2026Revised13 Oct 2026Reading12 minVersionv1.2ConfidenceHigh
§0b

Opinion

Read the call rather than the body. The name and the parameters say what happens, or the work is not finished. Most teams agree the name matters. The disagreement is the choice of name. The answer is rarely clever. The right name is the word the product owner uses, written in a type that says the same thing.

Naming makes F5 Self-Documenting Code possible. Naming gives F1 Single Responsibility its evidence: a function that resists a name is doing two things. The name is the diagnostic that catches it before the test does. Naming brings T1 Domain-Driven Types from the type system into the prose: a parameter named id: string admits anything the compiler counts as a string. Rename it userId: UserId and the call site, the signature and the type all say the same thing.

Generated code makes the bar harder to hold. Models abbreviate by habit. Reviewers approve proc because the prompt was about processing. Six months later someone reads proc(o) and pings the channel. Block the merge on the vocabulary rather than the abbreviation. If the product owner cannot read the call site without a glossary, the name has not finished.

Copy a note and link

Grab this short comment and drop it into a PR comment or an LLM chat to prompt the right change.

Function name and parameters should tell the reader what the call does. If they don't, rename until they do.

/tenet/intention-revealing-names/F2
Copy for paste
§0c

AI eyes only

Rule: the signature is the spec. A reader of name + parameters knows what the call does.

Reject: handle, process, do, data, info, obj, tmp, single-letter identifiers (except loop counters in trivial scope), and abbreviations not in the project glossary.

Generate: verb-led function names that name the outcome rather than the mechanism. Parameter names that name the role rather than the type. Branded primitive types (UserId, EmailAddress) over string.

Diagnostic: state the function in one sentence using only the name and parameter names. If that sentence is wrong or empty, rename before continuing.

§0d

Why?

  • The call site is self-contained: no comment, no wiki link, no tribal memory.
  • Honest names make single-purpose units visible; vague names smuggle multi-job functions past review.
  • Feeds self-documenting code, when names work, explanatory comments rot less.
  • Pairs with domain-driven types: OrderId over string; the name and the type say the same thing.
  • Test titles become assertions in prose: the failure message reads like a specification, not a stack trace riddle.
  • Distinct nouns improve search, cross-repo navigation, and code-intel recall.
  • Reviewers validate behaviour against a promise they can see in the header. Less working memory, fewer subtle approvals.
The receipts
Origins, quoted passages, evidence, the strongest counter-argument and the reply.
§1

Origins

Robert C. Martin's Clean Code (2008) opens the case in chapter two: meaningful names, pronounceable identifiers, avoiding encodings. The craft advice still anchors most onboarding reading lists.1

Martin Fowler catalogued the opposite smell in Refactoring (2nd edition, 2018): “Mysterious Name” flags an identifier where something important is insufficiently clear, with renaming as the first move before any comment is added.2

Joshua Bloch's Effective Java (3rd edition, 2018) builds the interfaces-and-types half of the story: APIs read as short sentences in the problem domain when the names are right.3 Steve McConnell treats identifiers as part of documentation engineering in Code Complete (2nd edition, 2004): identifiers are the documentation that survives when the wiki does not.4

John Ousterhout's A Philosophy of Software Design (2018) warns against cleverness that optimises for keystrokes over depth: obscure names leak complexity outward, and clarity wins over puns unless the pun is shared vocabulary.5

§2

Quotes

The name of a variable, function, or class should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.

Robert C. Martin · Clean Code (2008), ch. 2

Rename Symbol / Change Function Declaration: the smell is obscurity. The first refactor is almost always the name.

Martin Fowler · Refactoring 2e website · Mysterious Name

Use meaningful, pronounceable, searchable names. Avoid cryptic abbreviations and single-letter names, except as local variables whose scope is very small.

Joshua Bloch · Effective Java, 3rd ed. · Item 68

The best names are ones that reinforce understanding at the point of use and do not need to be deciphered.

Steve McConnell · Code Complete 2e · Good Variable Names
§3

Evidence

16 external sources, ranked by author authority. The first five are the canon; expand to see the rest, including the qualifiers and the named opposers. Each links out to its primary source.

  1. 01
    Robert C. Martin · 2008
    The canonical craft primer: intention-revealing names, pronounceability, avoiding mental mapping.
  2. 02
    Martin Fowler · 2018
    Names are the first refactor when behaviour is unclear at the callsite.
  3. 03
    David Thomas & Andrew Hunt · 2019
    Shared vocabulary collapses naming debates. One word per concept across code and speech.
  4. 04
    Eric Evans · 2003
    Code idioms should track domain speech: ties identifiers to product language explicitly.
  5. 05
    Steve McConnell · 2004
    Treats naming as a documentation strategy. Ties identifier quality to comprehension speed.
  1. 06
    Joshua Bloch · 2018
    Java ecosystem standard: readable API surfaces, minimal abbreviation, searchable symbols.
  2. 07
    John Ousterhout · 2018
    Depth and module boundaries matter as much as local names: shallow good names on a leaky abstraction still lose.
  3. 08
    Linus Torvalds & contributors · 1995 onwards
    C culture: descriptive identifiers, no cryptic abbrevs unless the expansion is longer than the benefit.
  4. 09
    Peter Hilton · 2016
    Naming as deliberate design: concrete nouns, domain verbs, iteration until honest.
  5. 10
    Kevlin Henney · 2010
    Code should say what it does. Names carry much of that load before comments earn space.
  6. 11
    Sam Hughes (qntm) · 2020
    Critique of Clean Code dogma: over-extraction and noisy prose. Naming advice still holds but context matters.
  7. 12
    Dustin Boswell & Trevor Foucher · 2011
    Readable code series naming chapter aligns with intention-first naming for maintenance teams.
  8. 13
    Guido van Rossum et al. · 2001 onwards
    Public API snake_case discipline: names are part of import surfaces, not private scribbles.
  9. 14
    Google · 2018 onwards
    Large-org consistency rules for identifiers: teams trade local flair for cross-repo legibility.
  10. 15
    Rust Project · 2024
    Type/trait/function casing rules so std-lib shaped code reads predictably.
  11. 16
    Peter Hilton · 2014
    Conference frame: naming difficulty is tolerance for bad names, not laws of nature.

Sixteen sources across supports and a few qualifiers. The opposer row is mostly about how far to take Uncle Bob's bundle rather than about skipping honest names. Where DDD and Pragmatic Programmer agree, the vocabulary is product-owned before it is keyboard-owned.

§4

Examples

Viewing: TypeScript.
Avoid

Before names hide what is being compared to what.

Filebilling.ts
function check(u: { subEnd: Date }, d: Date): boolean {
  return u.subEnd.getTime() < d.getTime();
}
Prefer
Filebilling-names.ts
function isSubscriptionExpired(user: { subscriptionEndsAt: Date }, asOf: Date): boolean {
  return user.subscriptionEndsAt.getTime() < asOf.getTime();
}
§4b

Enforcement

Viewing: TypeScript.

Apply these rules in eslint.config.mjs. The full enforcement across every tenet lives on the implementation page.

RuleToolCatches
@typescript-eslint/naming-conventiontypescript-eslintparameters, locals, functions and types that don’t match the agreed camel / Pascal split.
unicorn/name-replacementseslint-plugin-unicornerr, evt, btn, doc, str, num, strBuf: the abbreviations that hide the reader’s question.
id-lengthESLint coresingle-letter locals outside your explicit exceptions list.
eslint.config.mjsconfiguration snippet
import tseslint from 'typescript-eslint';
import unicorn from 'eslint-plugin-unicorn';

export default tseslint.config({
  files: ['**/*.{ts,tsx}'],
  plugins: { unicorn },
  rules: {
    'id-length': ['error', { min: 2, max: 48, exceptions: ['_', 'id', 'x', 'y', 'to'] }],
    'unicorn/name-replacements': ['error', {
      allowList: { Param: true, Ref: true, Props: true },
      checkShorthandProperties: true,
    }],
    '@typescript-eslint/naming-convention': [
      'error',
      { selector: 'variable', format: ['strictCamelCase', 'UPPER_CASE'], leadingUnderscore: 'allow' },
      { selector: 'function', format: ['strictCamelCase'] },
      { selector: 'typeLike', format: ['StrictPascalCase'] },
      { selector: 'parameter', format: ['strictCamelCase'], leadingUnderscore: 'allow' },
    ],
  }
});
§4c

AI rules

File.cursor/rules/f2-intention-revealing-names.mdc
---
alwaysApply: true
---

## Prickles F2: Intention-Revealing Names

Use names that answer why this exists and what it does in the domain vocabulary. If the signature does not hold the meaning, rename.

Functions state verbs in plain language. Values and parameters are nouns or noun phrases. Booleans read as predicates (isExpired, hasBalance).

Refuse placeholders at review: tmp, data, info, handle, process, manager, helper, unless the PR body defines the missing noun they replace.

Match local convention (camelCase, snake_case, PascalCase) but never hide meaning behind brevity a newcomer cannot pronounce.

When splitting under F1, each new unit must earn a name that fits the story the callsite tells.

Repo layout, CI, and ESLint wiring for these paths live on /implementation, not repeated on every tenet.

§5

Counter-argument

Counter

The steelman is keyboard fatigue and long identifiers in narrow columns: eight well chosen English words can wrap worse than eight clever abbreviations. Dense maths, physics, and cryptographic code also import symbols that look terse because the paper did. In those domains the glossary lives beside the code and abbreviations are community contract, not laziness.

§6

Counter-argument retort

Reply

Width is an editor problem. Reader confusion is a product problem. Wrap rules and column limits adjust. When an identifier is long because the concept is long, the prompt is to introduce a domain type or extract a function with a shorter honest name, not to revert to mgr.

For notation-heavy kernels, the abbreviation is itself intention-revealing inside that community. Put the paper citation or standard section ID next to the module: the name stays honest for its declared audience.

Default stance for application code stays: pronounceable domain words, predicates on booleans, verbs on operations, nouns on data. Everything else is an exception that gets defended in the PR description.

§7

Notes

  1. [1]Robert C. Martin: Clean Code (Prentice Hall, 2008), ch. 2: meaningful, intention-revealing names as the first layer of expression.
  2. [2]Martin Fowler: Refactoring, 2nd ed. (2018). Mysterious Name is smell #1 online. Rename operations are the prescribed first move.
  3. [3]Joshua Bloch: Effective Java, 3rd ed. (2018). Item 68 and surrounding items tie package/type/member naming to readable APIs.
Disagree? Found a hole in the argument? Take issue with this tenet →
Last revised: 2026-10-13