|
| 1 | +--- |
| 2 | +slug: /resources/style-guide |
| 3 | +title: Naming Variables & Functions |
| 4 | +description: Naming conventions for FlutterFlow, including guidelines for widgets, components, state variables, constants, and more. |
| 5 | +tags: [Style Guide, Variables] |
| 6 | +keywords: [Style Guide, Variables] |
| 7 | +--- |
| 8 | + |
| 9 | +# Naming Variables & Functions |
| 10 | + |
| 11 | +To make your code more maintainable, readable, and consistent, it’s essential to adopt clear naming conventions for variables, functions, and components. |
| 12 | + |
| 13 | +Best practices for naming conventions in app development (especially for projects using Flutter), aim to improve code readability, maintainability, and consistency across the application. Here are some general guidelines tailored for different aspects of a Flutter project: |
| 14 | + |
| 15 | +Various naming styles (as suggested by [Dart Effective Style Guide](https://dart.dev/effective-dart/style#identifiers)): |
| 16 | + |
| 17 | +- **UpperCamelCase** names capitalize the first letter of each word, including the first. |
| 18 | + |
| 19 | +- **lowerCamelCase** names capitalize the first letter of each word, except the first which is always lowercase, even if it's an acronym. |
| 20 | + |
| 21 | +- **lowercase_with_underscores** names use only lowercase letters, even for acronyms, and separate words with _. |
| 22 | + |
| 23 | + |
| 24 | + |
| 25 | +**General Principles** |
| 26 | +- **Be Consistent:** Whatever conventions you choose, apply them consistently across the project. |
| 27 | +- **Be Descriptive:** Names should be self-explanatory, reducing the need for additional comments to explain what a variable, function, or class does. |
| 28 | +- **Avoid Abbreviations:** Unless it's a well-known abbreviation, spell out words to avoid confusion. |
| 29 | + |
| 30 | + |
| 31 | +## Variable Naming Convention |
| 32 | +This section outlines naming conventions for pages, components, state variables, custom data types, enums, and constants to ensure clarity and consistency throughout the project. |
| 33 | + |
| 34 | + |
| 35 | +### Pages & Components |
| 36 | +Use **UpperCamelCase** for all widgets, components, pages, and screen names to maintain consistency and readability. FlutterFlow ensures clarity by automatically adding "Widget" to widget names when generating code. For components, you can suffix the name with "Component" to clearly distinguish them. |
| 37 | + |
| 38 | +Similarly, for pages and screens, include "Page" or "Screen" in the name to indicate their purpose. This approach aligns with Dart conventions for class names and ensures a well-organized project structure. |
| 39 | + |
| 40 | +:::tip[Do's] |
| 41 | +- **Use UpperCamelCase for Names:** Always use **UpperCamelCase** for widgets, components, pages, and screens. Examples: `CustomButton`, `UserProfilePage`, `MainViewComponent`. |
| 42 | + |
| 43 | +- **Include "Screen" or "Page" in Page Names:** Use "Screen" or "Page" in file names to identify UI screens or pages. Examples: `LoginScreen`, `SettingsPage`. |
| 44 | + |
| 45 | +- **Use Prefixes for Clarity When Necessary:** Add a prefix if it significantly improves clarity or prevents naming conflicts. Example: `AdminUserProfile` (to differentiate it from `CustomerUserProfile` or `UserProfile`). |
| 46 | + |
| 47 | +- **Be Descriptive and Clear in File Names:** Ensure names are descriptive enough to convey their purpose at a glance. Examples: `OrderConfirmationScreen`, `ProductDetailsPage`. |
| 48 | +::: |
| 49 | + |
| 50 | +:::danger[Don'ts] |
| 51 | +- **Don’t Use Unnecessary Prefixes:** Avoid prefixes that do not add clarity or are redundant. Bad Example: `AppPrimaryButton` (if `PrimaryButton` is sufficient). |
| 52 | + |
| 53 | +- **Don’t Add "Widget" Explicitly:** Avoid adding "Widget" to class or component names manually, as FlutterFlow already appends it during code generation. Bad Examples: `ButtonWidget`, `ProfileCardWidget`. |
| 54 | + |
| 55 | +- **Don’t Use LowerCamelCase for Class Names:** Reserve **lowerCamelCase** for variables and methods, not for components, or pages. Bad Examples: `loginButton`, `userProfile`. |
| 56 | + |
| 57 | +- **Don’t Mix Naming Conventions:** Maintain consistency with UpperCamelCase for all widgets, components, pages, and screens. Bad Examples: `userLogin`, `Profilecard`, `headerView`. |
| 58 | + |
| 59 | +- **Don’t Use Generic Names Without Purpose:** Avoid overly generic names that do not clearly convey the file’s intent. Bad Examples: `Main`, `View`, `Screen1`. |
| 60 | + |
| 61 | +::: |
| 62 | + |
| 63 | + |
| 64 | +Note that the style guidelines for Pages and Components also apply to **[Custom Widgets](../ff-concepts/adding-customization/custom-widgets.md)**, as Pages and Components created in FlutterFlow are internally generated as widgets. |
| 65 | + |
| 66 | + |
| 67 | +### Custom Data Types & Enums |
| 68 | + |
| 69 | +When naming custom data types and enums, use **UpperCamelCase** for consistency and clarity. Ensure that names are descriptive, providing a clear representation of the entity or purpose. |
| 70 | + |
| 71 | +:::tip[Do's] |
| 72 | + |
| 73 | +- **Use UpperCamelCase for Custom Data Types:** Name your custom data types using **UpperCamelCase**. Ensure that names are clear, concise, and descriptive, reflecting the entity they represent. Good Examples: `UserModel`, `ProductDetails`, `OrderItem`. |
| 74 | + |
| 75 | +- **Use consistent naming for Enum Names and Values:** Use **UpperCamelCase** for the enum name such as, `Status`, `ConnectionState`, `UserRole` and **lowerCamelCase** for its values e.g., `{active, inactive, pending}`. This approach aligns with Dart's enum naming guidelines and ensures consistency. |
| 76 | + |
| 77 | +- **Use Plural Names for Lists:** If the data type represents a List, use a plural name to clarify its purpose. Good Example: `OrderItems` (to represent multiple `OrderItem` objects). |
| 78 | +::: |
| 79 | + |
| 80 | +:::danger[Don'ts] |
| 81 | + |
| 82 | +- **Don’t Use All Lowercase or Mixed Case for Custom Data Types:** Avoid using all lowercase or inconsistent casing in data model class names, as it reduces readability. Bad Example: `usermodel`, `product_details`. |
| 83 | + |
| 84 | +- **Don’t Use Vague or Non-Descriptive Names**: Avoid using generic or unclear names that do not clearly describe the data entity. Bad Example: `DataModel`, `Entity`, `Item`. |
| 85 | + |
| 86 | +- **Don’t Mix Naming Conventions for Enums:** Maintain consistent capitalization between enum names and their values. Bad Example: `enum UserRole { Admin, EDITOR, viewer }` |
| 87 | +::: |
| 88 | + |
| 89 | +### Constants |
| 90 | + |
| 91 | +Flutter prefers using a lowercase `k` prefix for constants to indicate their immutability, especially for project-specific constants. This approach is more concise and aligns with Dart's common practices. Use **SCREAMING_SNAKE_CASE** only when contributing to global or legacy projects where it is already in use. |
| 92 | + |
| 93 | +:::tip[Do's] |
| 94 | +- **Start Constants with a k Prefix:** Always use a lowercase `k` followed by **UpperCamelCase** for constants in FlutterFlow projects. |
| 95 | +- **Use Descriptive and Contextual Names:** Clearly describe the purpose of the constant. Avoid using abbreviations unless they are widely understood. Examples: `kDefaultPadding`, `kMaxUploadSizeMb` |
| 96 | +::: |
| 97 | + |
| 98 | +:::danger[Don'ts] |
| 99 | +- **Don’t Omit the k Prefix for Constants:** Avoid using plain names for constants in a Flutter-specific project, as they might conflict with variables or methods. Bad Examples: `padding`, `uploadSize`. |
| 100 | +- **Don’t Use Vague or Generic Names:** Avoid using names that fail to describe the purpose of the constant. Bad Examples: `VALUE`, `DATA`, `X`, `Y`. |
| 101 | +::: |
| 102 | + |
| 103 | +### State Variables |
| 104 | + |
| 105 | +State variable names follow the **lowerCamelCase** naming style to align with Dart's conventions. |
| 106 | + |
| 107 | +:::tip[Do's] |
| 108 | +- **Be Descriptive and Clear:** Use variable names that clearly describe their purpose, avoiding generic or vague terms. Examples: `isFormValid`, `errorMessage`, `availableProducts`. |
| 109 | +- **Prefix Boolean Variables with `is`, `has`, or `should`:** For readability, use prefixes that denote the variable's purpose when naming Boolean values. Examples: `isActive`, `hasErrors`, `shouldReload`. |
| 110 | +- **Use Consistent Prefixes to denote state:** When managing UI or asynchronous state, use prefixes like `current`, `selected`, or `pending` for better context. Examples: `currentTabIndex`, `selectedUserId`, `pendingAction`. |
| 111 | +::: |
| 112 | + |
| 113 | +:::danger[Don'ts] |
| 114 | +- **Don’t Use Abbreviations or Single Letters:** Avoid abbreviations or single-character names that obscure the variable's intent. Bad Examples: `usrNm`, `f`, `cnt`. |
| 115 | +- **Don’t Use Generic Names:** Avoid using generic terms that do not convey the variable’s purpose. Bad Examples: `data`, `value`, `temp`. |
| 116 | +- **Don’t Start State Variables with Uppercase:** Follow Dart conventions by starting variable names with lowercase. Bad Examples: `UserName`, `IsLoading`. |
| 117 | +::: |
| 118 | + |
| 119 | +## Function Naming Convention |
| 120 | +This section defines naming conventions for custom functions, actions, and action blocks to maintain consistency, readability, and ease of understanding across the codebase. |
| 121 | + |
| 122 | +### Custom Functions & Actions |
| 123 | + |
| 124 | +Custom functions and custom actions created in the Custom Code tab of FlutterFlow should follow the **lowerCamelCase** naming convention. These typically reflect an action or behavior. |
| 125 | + |
| 126 | +:::tip[Do's] |
| 127 | +- **Be descriptive and concise:** Use clear, meaningful names that describe the action or purpose of the function (e.g., `validateForm` instead of `doCheck`, or `fetchUserData` instead of `userData`). |
| 128 | +- **Use action-oriented names:** Start with verbs to indicate behavior (e.g., `submitForm`, `processPayment`). |
| 129 | +::: |
| 130 | + |
| 131 | +:::danger[Dont's] |
| 132 | +- **Avoid using underscores or spaces:** Names like `fetch_user_data` do not align with **lowerCamelCase** conventions. |
| 133 | +- **Avoid redundant prefixes or suffixes:** There’s no need to prefix with `custom` or suffix with `Func` unless absolutely necessary for clarity (e.g., `customSubmitFormFunc` is redundant). |
| 134 | +- **Don’t use overly generic names:** Avoid vague terms like `doSomething` or `functionOne`, which don’t provide context. |
| 135 | +::: |
| 136 | + |
| 137 | +Note that **[Action Blocks](../resources/control-flow/functions/action-blocks.md)** should follow the same naming convention as custom actions, as they are both technically Dart functions internally in the generated code. |
0 commit comments