Flag Naming Conventions

Good feature flag names make your codebase easier to understand, your dashboard easier to navigate, and flag cleanup much simpler. This guide covers naming conventions that scale with your team.

Core Principles

Be Descriptive

Flag names should clearly communicate what the flag controls:

// Good: Clear purpose
'enable-dark-mode'
'show-beta-banner'
'use-new-payment-processor'

// Bad: Vague or unclear
'flag1'
'temp'
'new-feature'
'test'

Be Consistent

Pick a convention and stick with it across your entire codebase:

// Pick one style and use it everywhere
'enable-feature-name'  // verb-noun
'feature-name-enabled' // noun-verb
'is-feature-name'      // boolean prefix

Recommended Naming Patterns

Pattern 1: Action-Based (Recommended)

Use a verb prefix that describes what the flag does:

// Examples
const darkMode = flags['enable-dark-mode'];
const showBanner = flags['show-holiday-promo'];
const useNewApi = flags['use-v2-search-api'];

Pattern 2: Feature-Scoped

For larger features, prefix with the feature or domain:

// Checkout feature flags
'checkout-enable-express'
'checkout-show-upsells'
'checkout-use-stripe-v3'

// User profile flags
'profile-enable-avatars'
'profile-show-activity-feed'
'profile-allow-public-visibility'

This groups related flags together in your dashboard:

Pattern 3: Team-Scoped

For larger organizations, prefix with the team name:

// Growth team flags
'growth-enable-referral-program'
'growth-show-signup-incentive'

// Platform team flags
'platform-use-new-cache'
'platform-enable-rate-limiting'

What to Avoid

Cryptic Abbreviations

// Bad: What does this mean?
'en_dk_md_v2'
'usr_prf_act'

// Good: Spelled out
'enable-dark-mode-v2'
'user-profile-activity'

Dates or Versions in Names

// Bad: Will be confusing later
'enable-feature-2024-01'
'new-checkout-v3'

// Good: Describe the purpose, not the timeline
'enable-streamlined-checkout'
'use-async-checkout-flow'

Personal Names or Ticket Numbers

// Bad: Meaningless to others
'johns-feature'
'jira-1234'
'test-flag-delete-me'

// Good: Describe the feature
'enable-bulk-export'
'show-advanced-filters'

Naming for Different Flag Types

Release Flags

For gradual rollouts of new features:

'enable-new-editor'           // Simple on/off
'rollout-redesigned-nav'      // Percentage rollout
'release-ai-suggestions'      // New capability

Experiment Flags

For A/B tests and experiments:

'experiment-pricing-page-v2'
'test-checkout-button-color'
'ab-homepage-hero-layout'

Operational Flags

For runtime control and kill switches:

'ops-enable-maintenance-mode'
'ops-disable-notifications'
'ops-use-fallback-cdn'

Permission Flags

For feature access control:

'allow-api-access'
'permit-bulk-operations'
'grant-admin-features'

Case Style

kebab-case (Recommended)

Most flag providers and SDKs work best with kebab-case:

'enable-dark-mode'
'show-beta-features'
'use-new-api'

snake_case

Common in Python and Ruby codebases:

'enable_dark_mode'
'show_beta_features'
'use_new_api'

camelCase

Works well with JavaScript object destructuring:

const { enableDarkMode, showBetaFeatures } = useFlags();

Enforcing Conventions

Code Review Checklist

Add flag naming to your PR review checklist:

• Flag name follows team naming convention
• Flag name clearly describes its purpose
• No abbreviations, dates, or ticket numbers
• Consistent with existing flags in same feature area

Linting Rules

Some teams add custom lint rules:

// Example ESLint rule concept
'feature-flags/naming-convention': ['error', {
  pattern: '^(enable|show|use|allow|require)-[a-z-]+$',
  message: 'Flag names must start with enable-, show-, use-, allow-, or require-'
}]

FlagShark Dashboard

Use FlagShark's dashboard to audit your flag names:

Renaming Flags

If you need to rename a flag:

Quick Reference

Related Documentation

• Flag Lifecycle - When to add and remove flags
• Flag Detection - How FlagShark finds flags
• Configuration - Customizing flag detection patterns