naming-conventions（命名约定）

Naming Conventions

Universal principles for clear, intention-revealing names. Language-agnostic—applies to TypeScript, Go, Rust, Python, etc.

Core Principle

Names should reveal intent and domain, not implementation.

• users not userArray (domain, not data structure)
• calculateTax not doTaxCalculation (clear verb)
• PaymentProcessor not PaymentManager (specific action, not vague)

Prohibited Patterns

NEVER Use These Names

❌ Manager, Helper, Util

These are Ousterhout red flags — they're vague and don't reveal what the code does.

Bad:

UserManager
PaymentHelper
StringUtil

Good:

UserAuthenticator
PaymentProcessor
StringFormatter

Why: Naming forces design thinking. If you can't name it specifically, you don't understand what it does.

RARELY Use (Context-Dependent)

⚠️ Service, Handler, Processor, Controller

These can work when they're domain-specific or framework patterns, but prefer more specific names.

Bad (vague):

DataService         // What kind of data?
RequestHandler      // What kind of request?

Better (specific):

OrderService        // Domain context: orders
HttpRequestHandler  // Framework pattern: HTTP requests
PaymentProcessor    // Domain action: processing payments

SOMETIMES Acceptable

⚠️ Base, Abstract (prefixes)

Valid for framework/library code, but often hide intent in application code.

Framework (acceptable):

abstract class BaseComponent { ... }
abstract class AbstractRepository { ... }

Application (avoid):

// Better to name by domain
class Component { ... }              // If it's the base, no prefix needed
class Repository<T> { ... }         // Generic is clear without prefix

Always Avoid

❌ Generic containers: Manager, Helper, Util, Misc, Common ❌ Temporal names: step1, phase1, doFirst, doSecond ❌ Single letters: x, y, temp (except loop counters i, j, k) ❌ Vague abbreviations: usr, msg, ctx (except well-known: id, url, api, http)

Positive Patterns

Variables

Pattern: Descriptive nouns

Use domain language, not implementation:

✅ activeUsers       // Domain concept
✅ totalRevenue      // Clear business term
✅ selectedItems     // What they are

❌ userArray         // Implementation detail (array)
❌ rev               // Abbreviation (unclear)
❌ items             // Too vague (items of what?)
❌ data              // Maximally vague

Guidelines:

• Descriptive, not abbreviated
• Domain terms, not data structures (users, not userArray)
• Context matters: count alone is vague, activeUserCount is clear
• Avoid single-letter names except loop counters (i, j, k)

Functions

Pattern: Verb + noun

Describe the action:

✅ calculateTotal       // Clear action + target
✅ fetchUserData        // Action: fetch, target: user data
✅ isValidEmail         // Question: is valid?
✅ formatCurrency       // Transform: format

❌ total                // Missing verb (noun alone)
❌ getUserData          // Vague verb "get"
❌ validateEmail        // Returns boolean, use "is"
❌ currency             // Missing verb
❌ process              // Vague verb, no target

Guidelines:

• Start with clear verb (calculate, fetch, format, validate, parse, send, save)
• Pure functions: describe transformation (format, parse, convert)
• Side effects: verb implies action (save, send, fetch, update, delete)
• Boolean returns: use question prefix (is, has, can, should)
• Avoid vague verbs: get, do, handle, manage, process (without context)

Classes & Types

Pattern: Singular nouns

Use domain concepts:

✅ User                // Domain entity
✅ PaymentProcessor    // Action-specific
✅ OrderRepository     // Pattern adds meaning
✅ EmailNotifier       // Clear purpose

❌ Users               // Plural (unless collection type)
❌ PaymentManager      // Manager anti-pattern
❌ OrderDB             // Implementation leak
❌ EmailHelper         // Helper anti-pattern

Guidelines:

• Singular nouns (User, Order, Payment, not Users, Orders)
• Domain terms, not technical terms (Invoice, not BillingDocument)
• Pattern suffixes acceptable when they add meaning (Repository, Factory, Builder, Strategy)
• Avoid generic suffixes (Manager, Helper, Util, Handler without context)

Booleans

Pattern: Question prefix (is/has/can/should/will)

Prefix reveals boolean nature:

✅ isActive            // State question
✅ hasPermission       // Possession question
✅ canEdit             // Capability question
✅ shouldRefetch       // Conditional question
✅ willExpire          // Future state question

❌ active              // Ambiguous (could be status string)
❌ permission          // Looks like object
❌ editable            // Unclear (adjective, not question)
❌ enabled             // Past participle (prefer isEnabled)

Prefix meanings:

• is: State (isActive, isLoading, isValid, isEmpty)
• has: Possession (hasPermission, hasChildren, hasErrors)
• can: Capability (canEdit, canDelete, canSubmit)
• should: Conditional (shouldRefetch, shouldValidate)
• will: Future (willExpire, willRetry)

Why questions work: Boolean names should read like yes/no questions.

Collections

Pattern: Plural indicates multiple items

Use plural, avoid type suffixes:

✅ users               // Plural indicates collection
✅ selectedItems       // What they are, plural
✅ errorMessages       // Clear and plural
✅ userById            // Keyed collection (by what)

❌ userList            // Redundant type suffix
❌ userArray           // Implementation leak
❌ userCollection      // Redundant suffix
❌ item                // Singular for plural collection

Keyed collections (maps/dictionaries):

✅ userById            // By key type
✅ configByEnv         // By environment
✅ productsByCategory  // Grouped by category

❌ userMap             // Type suffix redundant
❌ users               // Unclear it's keyed (ambiguous)

Context-Aware Exceptions

Some generic names have valid domain justification:

Framework Patterns

✅ When acceptable:

• EventManager in event-driven system (but EventBus is better)
• ApiService wrapping external API (but ApiClient is clearer)
• RequestHandler in HTTP framework (framework convention)
• BaseComponent in UI framework (inheritance pattern)

Still prefer specific names when possible.

Repository Pattern

✅ Acceptable:

UserRepository
OrderRepository

This is a well-known pattern. The suffix adds meaning.

Factory Pattern

✅ Acceptable:

UserFactory
ComponentFactory

Pattern name clarifies purpose.

Quick Reference

Pattern Templates

Variables: Descriptive nouns

activeUsers, totalCount, selectedItem, currentPage

Functions: Verb + noun

calculateTotal, fetchUser, formatDate, parseJson

Booleans: Question prefix

isActive, hasPermission, canEdit, shouldRefetch

Classes: Singular noun (+ pattern if meaningful)

User, Order, PaymentProcessor, OrderRepository

Collections: Plural nouns

users, items, errors, messages

Examples: Before & After

Example 1: Vague to Clear

❌ Before:

class DataManager
  processData(data)
  getData()

✅ After:

class OrderProcessor
  calculateOrderTotal(order)
  fetchActiveOrders()

Example 2: Implementation to Domain

❌ Before:

userArray = fetchFromDB()
dataList = parseJsonString(response)

✅ After:

users = fetchUsers()
orders = parseOrderResponse(response)

Example 3: Temporal to Functional

❌ Before:

function step1(data)
function step2(data)
function step3(data)

✅ After:

function validateData(data)
function enrichData(data)
function persistData(data)

Philosophy

"If you can't name it, you don't understand it."

Naming is thinking. Bad names indicate unclear thinking. Good names indicate clear understanding.

Naming forces design decisions:

• Can't name a class? Maybe it's doing too much.
• Name is vague (Manager/Helper)? Unclear responsibility.
• Name is long (UserAccountPaymentProcessorManager)? Poor abstraction.

Use domain language:

• Domain experts should understand your names
• Names should match business concepts
• Avoid technical jargon when domain terms exist

Names are for humans, not compilers.

Write names for the person who reads your code in 6 months. That person is future you.