FSM: Naming Conventions

Common Patters to Define States

Thoughtful naming strategies form the cornerstone of maintainable finite state machines, transforming technical specifications into self-documenting workflows that communicate intent clearly to both developers and stakeholders. As state machine complexity grows, consistent nomenclature becomes essential for team collaboration, reducing the mental overhead required to understand system behavior and preventing miscommunication during development and maintenance phases.

Rather than imposing rigid rules, these conventions provide adaptable frameworks that respect domain-specific terminology while maintaining readability across different business contexts. When applied systematically, well-chosen names enable state machines to function as living documentation that accurately reflects business processes, making them valuable tools for implementation, communication, and long-term system evolution.

State Naming Guidelines

Use Action-Oriented Names

States often represent an action or a condition of an entity. Use descriptive, action-oriented names to make their purpose clear.

// ✅ Good: Clear action-oriented names
"SendMessage", "HandleError", "ValidateInput"
"ProcessingOrder", "LoadingData", "ConnectingToServer"

// ❌ Avoid: Generic or vague names
"State1", "CurrentState", "Process"

Choose Consistent Verb Patterns

Stick to a single tense pattern across all state names, typically present participle (-ing verbs) to indicate ongoing activities.

// ✅ Consistent present participle pattern
"Loading", "Processing", "Waiting", "Authenticating", "Validating"

// ✅ Alternative: Adjective pattern for conditions
"Ready", "Complete", "Failed", "Idle", "Busy"

// ❌ Avoid: Mixing tenses
"SendEmail", "ProcessingData", "Loaded" // Mixed patterns

Use PascalCase Consistently

Use PascalCase for all state names to maintain consistency.

// ✅ Correct PascalCase
"SendMessage", "HandleError", "ProcessingOrder"

// ❌ Avoid other cases
"send_message", "HANDLE_ERROR", "processing-order"

Keep Names Concise but Descriptive

Balance clarity with brevity, avoiding overly long or ambiguous names.

// ✅ Good balance
"ProcessingOrder", "ValidatingInput", "WaitingForResponse"

// ❌ Too verbose
"CurrentlyProcessingTheCustomerOrderInTheBackground"

// ❌ Too vague
"Process", "Handle", "Check"

Avoid Redundant Context

Do not include information already implied by the FSM structure or context.

// ✅ Clean names (when under OrderProcessing parent)
"Validating", "PaymentProcessing", "Shipping"

// ❌ Redundant prefixes
"OrderProcessing_Validating", "OrderProcessing_PaymentProcessing"

Use Domain-Specific Language

Match names with terminology used in your business domain.

// ✅ E-commerce domain
"BrowsingCatalog", "AddingToCart", "ProcessingCheckout", "ConfirmingOrder"

// ✅ Medical domain  
"SchedulingAppointment", "ReviewingSymptoms", "PrescribingMedication"

// ✅ Financial domain
"ValidatingAccount", "ProcessingTransfer", "ReconcilingBalance"

Event Naming Guidelines

Use Command Pattern for User Actions

Use imperative verbs for user-initiated events.

// ✅ User commands (camelCase)
"login", "logout", "submit", "cancel", "retry", "save", "delete"

Use Past Tense for System Events

Use past tense for system-generated events or completed actions.

// ✅ System notifications (camelCase)
"dataLoaded", "validationFailed", "timeoutOccurred", "paymentProcessed"

Use prefixes to organize related events when needed.

// ✅ Organized event groups
"api.requestSent", "api.responseReceived", "api.errorOccurred"
"ui.buttonClicked", "ui.formSubmitted", "ui.modalOpened"

Process Naming Guidelines

Name After Business Workflows

Choose process names that reflect the business workflow they represent.

// ✅ Business process names
"UserRegistration", "OrderFulfillment", "PaymentProcessing"
"ContentModeration", "InventoryManagement", "CustomerSupport"

Use Clear Technical Names

For technical processes, use descriptive names that indicate their purpose.

// ✅ Technical process names  
"DataSynchronization", "CacheManagement", "ErrorRecovery"
"SessionManagement", "BackupOperation", "DeploymentPipeline"

Practical Examples

Order Management System

// Top-level states
"CreatingOrder", "ProcessingOrder", "CompletingOrder", "CancellingOrder"

// Nested states under ProcessingOrder
"ValidatingOrder", "ProcessingPayment", "PreparingShipment"

// Events
"submitOrder", "paymentConfirmed", "validationFailed", "orderCancelled"

User Authentication System

// States
"Anonymous", "Authenticating", "Authenticated", "AccountLocked"

// Events  
"login", "loginSuccess", "loginFailure", "logout", "lockAccount"

Content Management Workflow

// States
"Draft", "UnderReview", "RevisionRequested", "Approved", "Published"

// Events
"submitForReview", "requestRevision", "approve", "publish", "archive"

Anti-Patterns to Avoid

Generic Names

// ❌ Avoid
"State1", "State2", "NextState", "PreviousState"

// ✅ Use specific names
"WaitingForInput", "ProcessingData", "DisplayingResults"

Implementation Details

// ❌ Avoid exposing implementation
"ComponentMounted", "UseStateUpdated", "EffectRunning"

// ✅ Focus on business meaning
"Ready", "Updating", "Synchronizing"

Negative Conditions

// ❌ Prefer positive conditions
"NotLoading", "NotReady", "NotAuthenticated"

// ✅ Use positive alternatives
"Idle", "Waiting", "Anonymous"

Consistency Checklist

Before finalizing names, verify: