Перейти к основному содержимому

Именование переменных и функций

Чтобы сделать код более удобным для поддержки, чтения и обеспечения единообразия, важно придерживаться четких правил именования переменных, функций и компонентов.

Лучшие практики правил именования в разработке приложений (особенно для проектов на Flutter) направлены на улучшение читаемости кода, его поддерживаемости и единообразия по всему приложению. Вот общие рекомендации, адаптированные для различных аспектов проекта на Flutter:

Различные стили именования (как предлагается в Эффективном стиле Dart):

  • UpperCamelCase (также известный как PascalCase) — имена, в которых первая буква каждого слова, включая первое, пишется с заглавной буквы.

  • lowerCamelCase (также известный как camelCase) — имена, в которых первая буква каждого слова, кроме первого, пишется с заглавной буквы; первое слово всегда начинается с маленькой буквы, даже если это аббревиатура.

  • lowercase_with_underscores (также известный как snake_case) — имена, использующие только строчные буквы, даже для аббревиатур, с разделением слов подчеркиваниями _.

various-naming-styles.png

Общие принципы

  • Соблюдайте единообразие: Какие бы правила вы ни выбрали, применяйте их последовательно по всему проекту.
  • Будьте описательны: Имена должны быть самодостаточными и понятными, чтобы не требовались дополнительные комментарии для объяснения, что делает переменная, функция или класс.
  • Избегайте сокращений: Если это не общепринятая аббревиатура, пишите слова полностью, чтобы избежать путаницы.

Правила именования переменных​

В этом разделе описаны правила именования для страниц, компонентов, переменных состояния, пользовательских типов данных, перечислений и констант, чтобы обеспечить ясность и единообразие по всему проекту.

Страницы и компоненты​

Используйте UpperCamelCase для всех виджетов, компонентов, страниц и имен экранов, чтобы обеспечить единообразие и читаемость. FlutterFlow автоматически добавляет суффикс "Widget" к именам виджетов при генерации кода, что повышает ясность. Для компонентов можно добавлять суффикс "Component", чтобы четко их отличать.

Аналогично, для страниц и экранов включайте в имя "Page" или "Screen", чтобы указать их назначение. Этот подход соответствует соглашениям Dart для имен классов и обеспечивает хорошо организованную структуру проекта.

comp-style-guide.png

Делайте

  • Используйте UpperCamelCase для имен: Всегда применяйте UpperCamelCase для виджетов, компонентов, страниц и экранов. Примеры: CustomButton, UserProfilePage, MainViewComponent.

  • Включайте "Screen" или "Page" в имена страниц: Используйте "Screen" или "Page" в именах файлов, чтобы идентифицировать экраны или страницы интерфейса. Примеры: LoginScreen, SettingsPage.

  • Используйте префиксы для ясности при необходимости: Добавляйте префикс, если он существенно улучшает ясность или предотвращает конфликты имен. Пример: AdminUserProfile (чтобы отличить от CustomerUserProfile или UserProfile).

  • Делайте имена файлов описательными и ясными: Убедитесь, что имена достаточно описательны, чтобы сразу передавать их назначение. Примеры: OrderConfirmationScreen, ProductDetailsPage.

Не делайте

  • Не используйте ненужные префиксы: Избегайте префиксов, которые не добавляют ясности или избыточны. Плохой пример: AppPrimaryButton (если PrimaryButton достаточно).

  • Не добавляйте "Widget" вручную: Не добавляйте "Widget" к именам классов или компонентов вручную, поскольку FlutterFlow уже добавляет его при генерации кода. Плохие примеры: ButtonWidget, ProfileCardWidget.

  • Не используйте lowerCamelCase для имен классов: Резервируйте lowerCamelCase для переменных и методов, а не для компонентов или страниц. Плохие примеры: loginButton, userProfile.

  • Не смешивайте правила именования: Соблюдайте единообразие с UpperCamelCase для всех виджетов, компонентов, страниц и экранов. Плохие примеры: userLogin, Profilecard, headerView.

  • Не используйте общие имена без смысла: Избегайте чрезмерно общих имен, которые не передают четко назначение файла. Плохие примеры: Main, View, Screen1.

Обратите внимание, что правила стиля для страниц и компонентов также применяются к пользовательским виджетам, поскольку страницы и компоненты, созданные в FlutterFlow, внутренне генерируются как виджеты.

Пользовательские типы данных и перечисления​

При именовании пользовательских типов данных и перечислений используйте UpperCamelCase для единообразия и ясности. Убедитесь, что имена описательны и четко отражают сущность или назначение.

dt-style-guide.png

Делайте

  • Используйте 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 для констант в проектах FlutterFlow.
  • Используйте описательные и контекстные имена: Четко описывайте назначение константы. Избегайте сокращений, если они не общеприняты. Примеры: kDefaultPadding, kMaxUploadSizeMb
Не делайте
  • Не опускайте префикс k для констант: Избегайте простых имен для констант в проектах на Flutter, поскольку они могут конфликтовать с переменными или методами. Плохие примеры: padding, uploadSize.
  • Не используйте расплывчатые или общие имена: Избегайте имен, которые не описывают назначение константы. Плохие примеры: VALUE, DATA, X, Y.

Переменные​

Имена переменных состояния и полей типов данных следуют стилю lowerCamelCase, чтобы соответствовать соглашениям Dart.

Делайте
  • Будьте описательны и ясны: Используйте имена переменных, которые четко описывают их назначение, избегая общих или расплывчатых терминов. Примеры: isFormValid, errorMessage, availableProducts.
  • Префиксируйте булевы переменные is, has или should: Для читаемости используйте префиксы, обозначающие назначение переменной при именовании булевых значений. Примеры: isActive, hasErrors, shouldReload.
  • Используйте последовательные префиксы для обозначения состояния: При управлении состоянием интерфейса или асинхронным состоянием применяйте префиксы вроде current, selected или pending для лучшего контекста. Примеры: currentTabIndex, selectedUserId, pendingAction.
Не делайте
  • Не используйте сокращения или одиночные буквы: Избегайте сокращений или имен из одной буквы, которые скрывают назначение переменной. Плохие примеры: usrNm, f, cnt.
  • Не используйте общие имена: Избегайте общих терминов, которые не передают назначение переменной. Плохие примеры: data, value, temp.
  • Не начинайте переменные с заглавной буквы: Следуйте соглашениям Dart, начиная имена переменных с маленькой буквы. Плохие примеры: UserName, IsLoading.

Правила именования функций​

В этом разделе определены правила именования для пользовательских функций, действий и блоков действий, чтобы обеспечить единообразие, читаемость и удобство понимания по всему коду.

Пользовательские функции и действия​

Пользовательские функции и пользовательские действия, созданные на вкладке Custom Code в FlutterFlow, должны следовать правилу lowerCamelCase. Они обычно отражают действие или поведение.

func-style-guide.png

Делайте
  • Будьте описательны и кратки: Используйте ясные, значимые имена, описывающие действие или назначение функции (например, validateForm вместо doCheck или fetchUserData вместо userData).
  • Используйте ориентированные на действие имена: Начинайте с глаголов, чтобы указать поведение (например, submitForm, processPayment).
Не делайте
  • Избегайте подчеркиваний или пробелов: Имена вроде fetch_user_data не соответствуют правилам lowerCamelCase.
  • Избегайте избыточных префиксов или суффиксов: Нет необходимости добавлять префикс custom или суффикс Func, если это не абсолютно необходимо для ясности (например, customSubmitFormFunc избыточно).
  • Не используйте чрезмерно общие имена: Избегайте расплывчатых терминов вроде doSomething или functionOne, которые не дают контекста.

Обратите внимание, что блоки действий должны следовать тем же правилам именования, что и пользовательские действия, поскольку внутренне в генерируемом коде они являются функциями Dart.