Skip to content

Commit 6fe6265

Browse files
talissoncostatalissoncosta
authored
docs: add feature flag naming conventions guide (#6618)
1 parent 2073683 commit 6fe6265

1 file changed

Lines changed: 141 additions & 0 deletions

File tree

‎docs/docs/best-practices/naming-conventions.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Flag Naming Conventions
3+
sidebar_label: Flag Naming Conventions
4+
sidebar_position: 9
5+
---
6+
7+
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.
8+
9+
## Why naming conventions matter
10+
11+
Feature flag names serve as identifiers throughout your codebase and within Flagsmith. A clear, consistent naming approach helps your team:
12+
13+
- **Find flags quickly** when searching in the dashboard or code
14+
- **Understand flag purpose** at a glance without reading documentation
15+
- **Avoid naming conflicts** as your flag count grows
16+
- **Maintain consistency** across teams and projects
17+
18+
:::caution
19+
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.
20+
:::
21+
22+
## Naming best practices
23+
24+
### Use descriptive, self-explanatory names
25+
26+
Flag names should communicate their purpose clearly. Anyone reading the name should understand what the flag controls without needing additional context.
27+
28+
| Recommended | Not recommended | Why |
29+
| --- | --- | --- |
30+
| `show_beta_dashboard` | `flag1` | Describes what the flag controls |
31+
| `enable_stripe_payments` | `payments` | Specifies the integration being toggled |
32+
| `max_upload_size_mb` | `size` | Indicates the value type and unit |
33+
| `allow_guest_checkout` | `gc` | Avoids cryptic abbreviations |
34+
35+
### Choose a consistent format
36+
37+
Pick a naming format and apply it consistently across your project. Common conventions include:
38+
39+
| Format | Example | Notes |
40+
| --- | --- | --- |
41+
| `snake_case` | `enable_dark_mode` | Most common, easy to read |
42+
| `kebab-case` | `enable-dark-mode` | Common in web development |
43+
| `camelCase` | `enableDarkMode` | Matches JavaScript conventions |
44+
| `SCREAMING_SNAKE_CASE` | `ENABLE_DARK_MODE` | Often used for constants |
45+
46+
### Consider prefixes and suffixes for organisation
47+
48+
Prefixes and suffixes can help group related flags and make searching easier:
49+
50+
**Common prefixes:**
51+
- `feature_` for new functionality: `feature_new_checkout_flow`
52+
- `experiment_` for A/B tests: `experiment_pricing_page_variant`
53+
- `ops_` for operational flags: `ops_maintenance_mode`
54+
- `kill_` for kill switches: `kill_external_api_calls`
55+
56+
**Common suffixes:**
57+
- `_enabled` for feature availability flags: `fb_ads_enabled`, `dark_mode_enabled`
58+
- `_limit` or `_max` for configuration values: `upload_size_limit`, `retry_max`
59+
60+
### Keep names concise but meaningful
61+
62+
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.
63+
64+
### Think about impact and context
65+
66+
When naming a flag, consider what information future maintainers need to know. A well-chosen name should help answer:
67+
68+
- **Which feature** does this flag relate to?
69+
- **What happens** when the flag is changed?
70+
- **Which users** are affected by this flag?
71+
- **Which components** or services use this flag?
72+
73+
For example, `checkout_guest_users_enabled` clearly indicates it affects the checkout feature, relates to guest users, and can be toggled on or off.
74+
75+
## Add descriptions to your flags
76+
77+
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:
78+
79+
- **Purpose**: Why was this flag created?
80+
- **Scope**: Which features, services, or components does it affect?
81+
- **Timeline**: Is this temporary or permanent?
82+
- **Dependencies**: Does it relate to other flags or external systems?
83+
84+
A clear description helps team members understand the flag's purpose even after 6 months, reducing the need to search through code or documentation.
85+
86+
:::tip
87+
Treat flag descriptions like code comments—they should explain the "why" and "what", not just repeat the flag name.
88+
:::
89+
90+
## Enforcing naming conventions
91+
92+
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.
93+
94+
### Configuring regex validation
95+
96+
1. Navigate to **Project Settings** → **General**
97+
2. Enable **Feature Name RegEx**
98+
3. Enter your regex pattern
99+
4. Click **Save**
100+
101+
Once configured, any attempt to create a flag that doesn't match the pattern will be rejected with a validation error.
102+
103+
### Example regex patterns
104+
105+
Here are common patterns you can use or adapt:
106+
107+
| Pattern | Description | Valid examples |
108+
| --- | --- | --- |
109+
| `^[a-z][a-z0-9_]*$` | Lowercase snake_case | `enable_feature`, `max_retries` |
110+
| `^[a-z][a-z0-9-]*$` | Lowercase kebab-case | `enable-feature`, `max-retries` |
111+
| `^[a-z][a-zA-Z0-9]*$` | camelCase starting lowercase | `enableFeature`, `maxRetries` |
112+
| `^[A-Z][A-Z0-9_]*$` | SCREAMING_SNAKE_CASE | `ENABLE_FEATURE`, `MAX_RETRIES` |
113+
| `^(feature\|experiment\|ops)_[a-z0-9_]+$` | Required prefix with snake_case | `feature_checkout`, `ops_debug` |
114+
115+
:::tip
116+
Test your regex pattern using the **Test RegEx** button before saving. This lets you verify the pattern works as expected with example flag names.
117+
:::
118+
119+
### Pattern requirements
120+
121+
The regex validation in Flagsmith:
122+
123+
- Automatically anchors patterns with `^` at the start and `$` at the end
124+
- Uses standard JavaScript regex syntax
125+
- Applies only to new flags (existing flags are not affected)
126+
127+
## Tag naming conventions
128+
129+
In addition to flag names, consider establishing conventions for [tags](/managing-flags/tagging). Tags help you categorise and filter flags, so consistent naming makes them more useful.
130+
131+
Common tag conventions:
132+
133+
- Use lowercase with hyphens: `backend`, `mobile-app`, `q1-2024`
134+
- Group by purpose: `team-payments`, `team-auth`, `deprecated`
135+
- Include lifecycle stage: `rollout-complete`, `ready-to-remove`
136+
137+
## Further reading
138+
139+
- [Feature Flag Lifecycles](/best-practices/flag-lifecycle) - understanding when to remove flags
140+
- [Structuring Your Projects](/best-practices/structuring-your-projects) - organising flags across projects
141+
- [Tagging](/managing-flags/tagging) - using tags to categorise flags

0 commit comments

Comments
 (0)