names that have to be decoded before they're understood

Naming Problems

Opaque abbreviations, inconsistent vocabulary, and classes named like verbs force the reader to reconstruct meaning the code should have stated outright.

Good names are the cheapest documentation you'll ever write.

01in the wild

In the wild

Opaque Abbreviations

Single letters and abbreviations make the reader rebuild meaning from the body.

example.py

# SMELL: what does this do? what is d? what is x?
def proc(d, x):
    return [i for i in d if i[1] > x]

# RIGHT: names carry the intent
def users_older_than(users, min_age):
    return [u for u in users if u.age > min_age]

proc/d/x force the reader to reconstruct meaning from the body. Verb-phrase functions and noun-phrase data tell the story.

// observed

proc(d, x):              opaque
users_older_than(...):   reads like a sentence

Inconsistent Vocabulary

Three words for one idea is three things to memorize and a daily source of confusion.

example.js

// SMELL: inconsistent words for the same idea
getUser(); fetchClient(); loadCustomer();   // user? client? customer?

// RIGHT: one consistent vocabulary, verb + noun
getCustomer(); listCustomers(); updateCustomer();

Consistency is a naming quality. One concept should wear one word everywhere it appears.

// observed

mixed:      three names, one concept, daily confusion
consistent: predictable API, less to memorize

Nouns and Verbs

Objects are noun phrases; methods are verb phrases; booleans read as yes/no questions.

example.ts

// SMELL: a class named like an action, a method named like a thing
class DoValidation {                 // a class is a noun, not a verb
  result(u: User): boolean { return u.age >= 18 }   // method should be a verb
}

// RIGHT: noun-phrase type, verb-phrase method, boolean as a question
class AgePolicy {
  isAdult(u: User): boolean { return u.age >= 18 }
}

Objects and classes are noun phrases; methods and functions are verb phrases; booleans read as questions (isAdult).

// observed

DoValidation.result(): backwards
AgePolicy.isAdult():   reads like a sentence

02weakness catalog

Mapped weaknesses (CWE)

On its own, this defect is catalogued by MITRE as one or more of these weaknesses. The exploitable vulnerability usually appears only when it chains or combines with another.