Имена переменных и функций
Хорошее имя экономит больше времени, чем любой комментарий: по нему сразу понятно, что делает переменная, функция или компонент. Ниже — соглашения, принятые во Flutter-проектах и применимые во FlutterFlow.
Три стиля написания (по Dart Effective Style Guide):
-
UpperCamelCase (он же PascalCase) — с заглавной каждое слово, включая первое.
-
lowerCamelCase (он же camelCase) — с заглавной каждое слово, кроме первого; первое всегда со строчной, даже если это аббревиатура.
-
lowercase_with_underscores (он же snake_case) — только строчные буквы, слова разделяются знаком
_; аббревиатуры тоже строчными.
Общие принципы
- Единообразие. Какие бы соглашения вы ни выбрали, держитесь их во всём проекте.
- Говорящие имена. Имя должно объяснять само себя, чтобы к нему не требовался комментарий.
- Без сокращений. Сокращайте только то, что понятно всем без расшифровки.
Именование переменных
Дальше — соглашения для страниц, компонентов, переменных состояния, собственных типов данных, перечислений и констант.
Страницы и компоненты
Для виджетов, компонентов, страниц и экранов используйте UpperCamelCase. Слово «Widget» FlutterFlow добавляет к именам виджетов сам при генерации кода. Компонентам можно дописывать суффикс «Component», чтобы отличать их от остального.
Страницам и экранам полезно дать в имени «Page» или «Screen» — тогда назначение видно без открытия. Это совпадает с конвенцией Dart для имён классов.
-
UpperCamelCase для имён. Виджеты, компоненты, страницы и экраны:
CustomButton,UserProfilePage,MainViewComponent. -
«Screen» или «Page» в именах страниц. Так экран видно по имени файла:
LoginScreen,SettingsPage. -
Префикс, когда он снимает неоднозначность.
AdminUserProfileрядом сCustomerUserProfile— оправданно. -
Понятное имя целиком. Назначение должно читаться с первого взгляда:
OrderConfirmationScreen,ProductDetailsPage.
-
Лишние префиксы.
AppPrimaryButton, когда достаточноPrimaryButton. -
Слово «Widget» вручную. FlutterFlow дописывает его сам при генерации кода:
ButtonWidget,ProfileCardWidget— избыточно. -
lowerCamelCase для классов. Он предназначен переменным и методам, а не компонентам и страницам:
loginButton,userProfile. -
Смешение стилей.
userLogin,Profilecard,headerView— в одном проекте так быть не должно. -
Безликие имена.
Main,View,Screen1ничего не говорят о содержимом.
Те же правила действуют для кастомных виджетов: страницы и компоненты FlutterFlow внутри тоже превращаются в виджеты.
Типы данных и перечисления
Собственные типы данных и перечисления называйте в UpperCamelCase, и пусть имя описывает сущность, а не абстракцию.
-
UpperCamelCase для типов данных. Кратко и по делу:
UserModel,ProductDetails,OrderItem. -
Единый стиль для перечислений. Имя — в UpperCamelCase (
Status,ConnectionState,UserRole), значения — в lowerCamelCase ({active, inactive, pending}). Так рекомендует Dart. -
Множественное число для списков. Если тип представляет список, это стоит отразить в имени:
OrderItemsдля набора объектовOrderItem.
-
Строчные буквы и разнобой в регистре.
usermodel,product_detailsчитаются хуже. -
Расплывчатые имена.
DataModel,Entity,Itemне описывают сущность. -
Разнобой в перечислениях.
enum UserRole { Admin, EDITOR, viewer }— три стиля в одной строке.
Поля типов данных именуются по тем же правилам, что и переменные состояния.
Константы
Во Flutter константы принято начинать со строчной k — она сразу говорит о неизменяемости. Это короче и ближе к практике Dart, чем SCREAMING_SNAKE_CASE; последний используйте, только если работаете в проекте, где он уже принят.
- Префикс k. Строчная
k, дальше UpperCamelCase. - Имя по назначению.
kDefaultPadding,kMaxUploadSizeMb— понятно, что за значение и в чём оно измеряется.
- Без префикса.
padding,uploadSizeлегко спутать с переменными и методами. - Общие слова.
VALUE,DATA,X,Yне объясняют, что хранится.
Переменные
Переменные состояния и поля типов данных пишутся в lowerCamelCase — как принято в Dart.
- Имя объясняет содержимое.
isFormValid,errorMessage,availableProducts. - Логические — с
is,hasилиshould.isActive,hasErrors,shouldReloadчитаются как утверждение, и условие с ними понятно без разбора. - Приставки состояния. Для UI и асинхронных данных удобны
current,selected,pending:currentTabIndex,selectedUserId,pendingAction.
- Сокращения и одиночные буквы.
usrNm,f,cnt— экономия трёх символов ценой ясности. - Общие слова.
data,value,tempничего не говорят. - Заглавная в начале.
UserName,IsLoadingнарушают конвенцию Dart.
Именование функций
Дальше — про кастомные функции, действия и блоки действий.
Кастомные функции и действия
То, что вы создаёте во вкладке Custom Code, называется в lowerCamelCase и обычно описывает действие.
- Точно и коротко.
validateFormвместоdoCheck,fetchUserDataвместоuserData. - С глагола. Имя должно называть действие:
submitForm,processPayment.
- Подчёркивания и пробелы.
fetch_user_dataне соответствует lowerCamelCase. - Лишние приставки и окончания.
customSubmitFormFunc— три слова из четырёх ничего не добавляют. - Безликие имена.
doSomething,functionOneне дают контекста.
Блоки действий называются по тем же правилам, что и кастомные действия: в сгенерированном коде это такие же функции Dart.