teqo-backup/.agents/skills/clean-code/references/naming-conventions.md
Francisco Ignácio Fontoura Solla b75daab498 Refactor campaign dashboard UX and add product discovery artifacts.
Extract dashboard cards into focused components (queues, upcoming plans, leadership status, recently visited, choropleth legend), compile the roadmap for outcome-oriented tracking, document the customer job and improve-app journey, and tighten roadmap skills with decision-quality gates.
2026-07-19 21:56:01 -03:00

11 KiB

Naming Conventions

Comprehensive guide to choosing names that reveal intent, avoid disinformation, and make code read like well-written prose. Based on Robert C. Martin's Clean Code, Chapter 2.

The Golden Rule

A name should tell you why it exists, what it does, and how it is used. If a name requires a comment to explain it, the name does not reveal its intent.


Intention-Revealing Names

The name of a variable, function, or class should answer three questions:

  1. Why does it exist?
  2. What does it do?
  3. How is it used?

Before and After

Before After Why it's better
d elapsedTimeInDays Reveals what the number represents
list flaggedAccounts Describes which list and why it exists
hp isHighPriority Self-documents its boolean nature and meaning
temp unprocessedBatchItems Communicates purpose, not temporary status
x, y latitude, longitude Domain language replaces abstract math symbols
val discountPercentage Specifies what value and its unit
data customerOrderHistory Names the specific data, not the generic concept
info shippingTrackingDetails Adds specificity to a meaningless suffix

Code Example

# BAD: What does this do?
def get_them(the_list):
    result = []
    for x in the_list:
        if x[0] == 4:
            result.append(x)
    return result

# GOOD: Intention is revealed
def get_flagged_cells(game_board):
    flagged_cells = []
    for cell in game_board:
        if cell.is_flagged():
            flagged_cells.append(cell)
    return flagged_cells

Avoiding Disinformation

Disinformation means using names that imply something different from the actual meaning.

Rules:

  • Don't use accountList unless it is actually a List type -- use accounts or accountGroup
  • Don't use names that vary in small ways: XYZControllerForEfficientHandlingOfStrings vs XYZControllerForEfficientStorageOfStrings
  • Don't use lowercase L or uppercase O as variable names (look like 1 and 0)
  • Don't use names of other well-known entities: hp, aix, sco are Unix platform names

Common Disinformation Patterns

Disinformation Problem Fix
accountList when it's a Set Implies ordered, duplicates allowed Use accounts
name1, name2 Implies ordering or relationship that doesn't exist Use meaningful distinction: firstName, lastName
strName Hungarian notation; type may change Just use name
theAccount vs account No meaningful distinction Pick one, use it consistently

Meaningful Distinctions

If names must be different, they should mean something different.

Noise words are meaningless distinctions:

  • Product vs ProductInfo vs ProductData -- what's the difference?
  • getAccount() vs getAccountInfo() vs getAccountData() -- indistinguishable
  • name vs nameString -- is name a floating-point number?

The test: If you cannot tell what two similarly named things do without reading their implementations, the names fail.

How to Make Meaningful Distinctions

Instead of Use Rationale
copyChars(a1, a2) copyChars(source, destination) Arguments reveal their role
moneyAmount vs money Just money Amount is implied by the context
theMessage vs message Just message The article adds no information
accountData vs account Just account Data is inherent -- what else would it be?

Pronounceable Names

If you cannot pronounce a name, you cannot discuss it without sounding foolish.

Unpronounceable Pronounceable
genymdhms generationTimestamp
modymdhms modificationTimestamp
pszqint formattedQuantity
cstmrAddr customerAddress

Why it matters: Programming is a social activity. You discuss code in reviews, pairing, design meetings, and stand-ups. Names you cannot say out loud create communication barriers.


Searchable Names

Single-letter names and numeric constants are impossible to search for in a large codebase.

Rule of thumb: The length of a name should correspond to the size of its scope.

Scope Name length Example
Single-line lambda 1 character acceptable items.map(x => x.id)
Loop body (3-5 lines) 1-2 characters acceptable for i in range(len(items))
Method scope Descriptive word(s) retryCount, matchingUser
Class scope Fully descriptive phrase maximumQueueCapacity
Module/global scope Complete, searchable phrase DEFAULT_CONNECTION_TIMEOUT_MS

Constants Must Be Named

// BAD: What does 5 mean? What does 7 mean?
if (retries > 5) { ... }
setTimeout(fn, 7 * 86400000);

// GOOD: Self-documenting
const MAX_RETRY_ATTEMPTS = 5;
const CACHE_EXPIRY_DAYS = 7;
const MS_PER_DAY = 86400000;

if (retries > MAX_RETRY_ATTEMPTS) { ... }
setTimeout(fn, CACHE_EXPIRY_DAYS * MS_PER_DAY);

Class Names vs. Method Names

Class Names: Nouns and Noun Phrases

Classes represent things. Their names should be nouns or noun phrases.

Good Bad Why
Customer CustomerManager Manager is vague -- what does it manage?
WikiPage WebPage More specific to the domain
AddressParser ParseAddress Noun phrase, not a verb
InvoiceRepository InvoiceProcessor Processor is vague -- what processing?
Account AccountData Data suffix is noise

Avoid: Manager, Processor, Data, Info -- these are weasel words that indicate the class has no clear responsibility.

Method Names: Verbs and Verb Phrases

Methods represent actions. Their names should be verbs or verb phrases.

Good Bad Why
save() doSave() do prefix is noise
calculateTax() tax() Verb clarifies it computes, not stores
isValid() checkValid() Boolean accessor follows is/has/can convention
fromJson(str) parse(str) Static factory name describes transformation
deleteExpiredSessions() cleanup() Specific about what gets cleaned

Accessor, Mutator, and Predicate Conventions

// Accessors: get + property
String getName()
int getAge()

// Mutators: set + property
void setName(String name)
void setAge(int age)

// Predicates: is/has/can + condition
boolean isEmpty()
boolean hasPermission(Role role)
boolean canExecute()

Naming Conventions by Language

Python

  • snake_case for functions and variables: calculate_total, user_count
  • PascalCase for classes: UserAccount, OrderProcessor
  • UPPER_SNAKE_CASE for constants: MAX_RETRIES, DEFAULT_TIMEOUT
  • _leading_underscore for private: _internal_cache
  • __dunder__ for magic methods: __init__, __str__

JavaScript/TypeScript

  • camelCase for functions and variables: calculateTotal, userCount
  • PascalCase for classes and components: UserAccount, OrderList
  • UPPER_SNAKE_CASE for constants: MAX_RETRIES, API_BASE_URL
  • #privateField for private class fields (ES2022+)

Java

  • camelCase for methods and variables: calculateTotal(), userCount
  • PascalCase for classes: UserAccount, OrderService
  • UPPER_SNAKE_CASE for constants: MAX_RETRIES
  • Packages: com.company.project.module

Go

  • PascalCase for exported (public): CalculateTotal, UserCount
  • camelCase for unexported (private): calculateTotal, userCount
  • Short names acceptable for small scopes: r for reader, w for writer
  • Acronyms stay uppercase: HTTPClient, XMLParser, userID

Rust

  • snake_case for functions and variables: calculate_total, user_count
  • PascalCase for types and traits: UserAccount, Serialize
  • UPPER_SNAKE_CASE for constants and statics: MAX_RETRIES
  • Lifetime names: short lowercase 'a, 'b or descriptive 'input, 'output

The Pick-One-Word-Per-Concept Rule

Using different words for the same abstract concept is confusing.

Inconsistent Consistent Rule
fetch / retrieve / get Pick get everywhere One word for the read operation
controller / manager / driver Pick controller everywhere One word for the coordination role
create / make / build / new Pick create for API, build for complex assembly Differentiate only if semantics differ
remove / delete / destroy delete for permanent, remove for detach Different words when semantics differ

Solution Domain vs. Problem Domain Names

Use solution domain names when the concept is a well-known computer science term:

  • Queue, Stack, HashMap, Factory, Visitor, Iterator
  • Fellow programmers will recognize these instantly

Use problem domain names when the concept belongs to the business:

  • Invoice, Shipment, PolicyHolder, ClaimAdjuster
  • Domain experts and future maintainers will understand these

The priority: Problem domain names first, solution domain names second. Code that reads in business terms is easier for the whole team -- developers, testers, product managers -- to discuss and verify.


Common Anti-Patterns

Names to Avoid

Anti-pattern Example Problem
Single letter a, b, t Meaningless outside tiny loops
Abbreviation acct, mgr, btn, usr Saves milliseconds, costs hours
Generic suffix DataObject, InfoManager Adds nothing; signals unclear responsibility
Type encoding sName, iCount, bFlag IDE shows types; encoding is obsolete and misleading
Numbered series arg1, arg2, arg3 Provides no information about each argument's role
Mental mapping r means URL (in the author's head) Forces readers to maintain a mental translation table
Puns add meaning both "concatenate" and "insert" Same word, different semantics creates confusion

Renaming Checklist

When renaming a variable, function, or class, follow this checklist to ensure the change improves clarity:

  1. Does the new name reveal intent? The reader should understand purpose without reading the implementation.
  2. Is it pronounceable? Can you say it in a code review without spelling it out?
  3. Is it searchable? Can you find all occurrences with a simple text search?
  4. Does it avoid disinformation? The name should not imply something the code does not do.
  5. Is it consistent with the codebase? Use the same word for the same concept everywhere.
  6. Is the length proportional to scope? Short names for tiny scopes, long names for large scopes.
  7. Does it use domain language? Prefer business terminology over generic programming terms.

Remember: Renaming is one of the most powerful refactorings. Modern IDEs make it safe and fast. Never hesitate to rename something that is unclear -- your future self and your teammates will thank you.