Naming Feature Flags: A Convention That Scales With Your Team

Use a consistent pattern of three parts, separated by a delimiter your tools accept:

1. Type. Why the flag exists: release (gradual rollout of new code), experiment (an A/B test), ops (a kill switch or load control) or permission (entitlement by plan or customer).
2. Area. The product or system domain, such as checkout, search or billing.
3. Behavior. What turns on, described in a few words.

Examples in kebab case: release-checkout-address-autocomplete, ops-search-disable-suggestions, experiment-onboarding-short-form and permission-reports-advanced-export.

The type prefix does real work. Release flags should be short-lived and deleted, ops flags may live for years, and permission flags belong to the pricing model. Seeing the type in the name tells reviewers how long the flag should exist.

Set a few hard rules and enforce them in review:

• One casing style everywhere. Pick kebab case or snake case for names, and one style in code constants. Mixed styles break searches.
• Name the on state. A flag called release-search-new-ranking means true turns the new ranking on. Avoid negatives such as disable-old-search, which make double negatives when the value is false.
• Describe behavior, not a ticket number or a person. Ticket IDs belong in metadata. Names like john-test or bug-4821 tell the next engineer nothing.
• No vague words. Avoid new, temp, test and v2 as the entire meaning.
• Keep names stable. Renaming a flag in code and in the platform at different times causes outages. Create a new flag instead and retire the old one.
• Respect tool limits. Check your platform's rules for allowed characters and length before you decide.

Names can't hold everything, so require these fields at creation:

• Owner. A team or person responsible for the flag.
• Purpose. One sentence on what it protects or enables.
• Ticket or link. The work item and the design note.
• Created date and planned removal date. Release and experiment flags should have one.
• Environments and default state. Where it's on, and what value applies if the flag service is unreachable.

Flag platforms such as LaunchDarkly and Flagsmith may offer tags, descriptions and other fields that carry this information, so confirm what each offers for your plan. A flag with an owner and a removal date is far easier to clean up; the feature flag cleanup guide explains that process.

You don't have to rename everything at once. Follow this plan:

1. Export your current flags and classify each as release, experiment, ops or permission.
2. Delete the dead ones first. Flags that are fully on or off everywhere, and referenced nowhere, cost nothing to remove.
3. Adopt the convention for all new flags immediately, and enforce it with a check in code review or a lint rule.
4. Rename active flags only when you touch them, by creating a new flag and moving the code, not by editing the old key in place.
5. Document the convention in the engineering handbook with three or four examples for each type.

If you're still choosing a platform, the LaunchDarkly, Split and Flagsmith comparison covers the trade-offs, and running a canary release with feature flags shows where good names pay off during a rollout.

These patterns turn a flag list into a junk drawer:

• Names that describe the implementation (use-redis-cache-v3) instead of the intent.
• Different names in code and the dashboard, so searching one finds nothing in the other.
• Reusing a flag key for a new purpose after the old one was deleted. Old client code or cached values may still read it.
• Encoding the environment in the name. Use the platform's environments instead.
• Nesting too deep. More than three or four segments become hard to read and to type.
• No type prefix, so nobody knows which flags are safe to delete.

Run a short review every quarter: sort the flag list by name and see whether each entry still makes sense to someone who wasn't there when it was created.