Skip to main content

Flag Naming Conventions

Consistent naming conventions make your feature flags easier to understand, search, and manage. This guide covers best practices for naming flags and how to enforce conventions using Flagsmith's built-in validation.

Why naming conventions matter​

Feature flag names serve as identifiers throughout your codebase and within Flagsmith. A clear, consistent naming approach helps your team:

  • Find flags quickly when searching in the dashboard or code
  • Understand flag purpose at a glance without reading documentation
  • Avoid naming conflicts as your flag count grows
  • Maintain consistency across teams and projects
caution

Features cannot be renamed after creation. Choose names carefully, as you'll need to create a new flag and migrate if you want to change a name later.

Naming best practices​

Use descriptive, self-explanatory names​

Flag names should communicate their purpose clearly. Anyone reading the name should understand what the flag controls without needing additional context.

RecommendedNot recommendedWhy
show_beta_dashboardflag1Describes what the flag controls
enable_stripe_paymentspaymentsSpecifies the integration being toggled
max_upload_size_mbsizeIndicates the value type and unit
allow_guest_checkoutgcAvoids cryptic abbreviations

Choose a consistent format​

Pick a naming format and apply it consistently across your project. Common conventions include:

FormatExampleNotes
snake_caseenable_dark_modeMost common, easy to read
kebab-caseenable-dark-modeCommon in web development
camelCaseenableDarkModeMatches JavaScript conventions
SCREAMING_SNAKE_CASEENABLE_DARK_MODEOften used for constants

Consider prefixes and suffixes for organisation​

Prefixes and suffixes can help group related flags and make searching easier:

Common prefixes:

  • feature_ for new functionality: feature_new_checkout_flow
  • experiment_ for A/B tests: experiment_pricing_page_variant
  • ops_ for operational flags: ops_maintenance_mode
  • kill_ for kill switches: kill_external_api_calls

Common suffixes:

  • _enabled for feature availability flags: fb_ads_enabled, dark_mode_enabled
  • _limit or _max for configuration values: upload_size_limit, retry_max

Keep names concise but meaningful​

Aim for names that are long enough to be descriptive but short enough to be practical. A good rule of thumb is 2-5 words.

Think about impact and context​

When naming a flag, consider what information future maintainers need to know. A well-chosen name should help answer:

  • Which feature does this flag relate to?
  • What happens when the flag is changed?
  • Which users are affected by this flag?
  • Which components or services use this flag?

For example, checkout_guest_users_enabled clearly indicates it affects the checkout feature, relates to guest users, and can be toggled on or off.

Add descriptions to your flags​

Whilst flag names cannot be changed after creation, descriptions can be updated at any time. Use the description field to provide context that doesn't fit in the name:

  • Purpose: Why was this flag created?
  • Scope: Which features, services, or components does it affect?
  • Timeline: Is this temporary or permanent?
  • Dependencies: Does it relate to other flags or external systems?

A clear description helps team members understand the flag's purpose even after 6 months, reducing the need to search through code or documentation.

tip

Treat flag descriptions like code comments—they should explain the "why" and "what", not just repeat the flag name.

Enforcing naming conventions​

Flagsmith allows you to enforce naming conventions at the project level using regular expressions. When configured, new flags must match the pattern before they can be created.

Configuring regex validation​

  1. Navigate to Project Settings → General
  2. Enable Feature Name RegEx
  3. Enter your regex pattern
  4. Click Save

Once configured, any attempt to create a flag that doesn't match the pattern will be rejected with a validation error.

Example regex patterns​

Here are common patterns you can use or adapt:

PatternDescriptionValid examples
^[a-z][a-z0-9_]*$Lowercase snake_caseenable_feature, max_retries
^[a-z][a-z0-9-]*$Lowercase kebab-caseenable-feature, max-retries
^[a-z][a-zA-Z0-9]*$camelCase starting lowercaseenableFeature, maxRetries
^[A-Z][A-Z0-9_]*$SCREAMING_SNAKE_CASEENABLE_FEATURE, MAX_RETRIES
^(feature|experiment|ops)_[a-z0-9_]+$Required prefix with snake_casefeature_checkout, ops_debug
tip

Test your regex pattern using the Test RegEx button before saving. This lets you verify the pattern works as expected with example flag names.

Pattern requirements​

The regex validation in Flagsmith:

  • Automatically anchors patterns with ^ at the start and $ at the end
  • Uses standard JavaScript regex syntax
  • Applies only to new flags (existing flags are not affected)

Tag naming conventions​

In addition to flag names, consider establishing conventions for tags. Tags help you categorise and filter flags, so consistent naming makes them more useful.

Common tag conventions:

  • Use lowercase with hyphens: backend, mobile-app, q1-2024
  • Group by purpose: team-payments, team-auth, deprecated
  • Include lifecycle stage: rollout-complete, ready-to-remove

Further reading​