Skip to main content

Names Reveal Intent

What This Concept Is​

A name is compressed documentation. When you name a class, method, or variable well, the reader learns three things at once:

  • what it is (domain or role)
  • why it exists (purpose)
  • how to use it (expected behavior)

A bad name forces the reader to reconstruct those three facts by scanning implementation, running a debugger, or guessing from usage. Every bad name is rented: you pay interest every time someone reads the code.

Clean Code's rule of thumb: if a name needs a comment to explain it, the name is failing.

Why It Matters Here​

Naming is where design becomes visible. A class named DataManager tells the reader almost nothing. A class named OrderExporter tells them the responsibility, the data involved, and the direction of work. Before we apply SOLID or refactor moves, we name things so that the problems become legible.

Naming is also the cheapest refactor available. Renames do not change behavior, can be verified by the compiler in typed languages, and frequently make further refactoring obvious.

Concrete Example​

Bad naming -- everything is "data":

def process(d):
    r = []
    for x in d:
        if x[2] > 0:
            r.append(x[0])
    return r

The reader has no idea what d is, what x[2] means, or what's being filtered.

Names that reveal intent:

def customer_ids_with_outstanding_balance(customers):
    ids = []
    for customer in customers:
        if customer.balance > 0:
            ids.append(customer.id)
    return ids

Now the function name states the result, and customer.balance makes the predicate obvious. The comment that would have lived above process is no longer needed.

Common Confusion / Misconception​

"Short names are clean names." Not in general. Short names are fine when the scope is tiny (i in a three-line loop) or when the name is a well-known convention (e for an exception in a catch). Long names pay for themselves whenever the distance between declaration and use is large.

A second misconception: "the name should say how it works." A name should say what it does and why, not how. bubbleSortCustomers is worse than sortedByName because the algorithm is implementation; the sort order is intent.

A third: "Hungarian-style type prefixes are informative." In modern typed languages they duplicate the compiler, and in untyped languages they lie as soon as the type changes.

How To Use It​

When writing or renaming, apply this drill:

  1. Write the one-line purpose out loud. If it needs an "and", either split the thing or split the name.
  2. Name by role, not by type (user not userMap; isActive not activeFlag).
  3. Prefer verbs for functions (compute, find, render) and nouns for classes (Order, Report).
  4. Avoid disinformation: accountList that is actually a Set lies.
  5. When you rename, delete any comment the rename obsoletes in the same commit.

Check Yourself​

  1. Why is a comment that describes what a method does often a naming failure?
  2. When is a very short name (like i) actually a good name?
  3. What is the difference between naming by role and naming by type?

Mini Drill or Application​

Pick any 200-line file you know. Do all four:

  1. Mark every name you had to read the body to understand.
  2. For each, propose a rename that makes the purpose clear at the declaration.
  3. Delete the comment above at least two of them, confirming the rename carries the information.
  4. Verify that usage sites still read correctly with the new name.

Read This Only If Stuck​