Читабельность кода

Соглашения об именовании

Общие соглашения об именовании

В этом разделе описываются соглашения об именовании «верблюжий регистр» и «регистр Pascal». Если вы уже знакомы с этими терминами, можете пропустить этот раздел.

Верблюжий регистр

Для элементов управления и переменных следует использовать верблюжий регистр. Верблюжий регистр начинается с префикса в нижнем регистре, из имен объектов или переменных удаляются все пробелы, а первая буква каждого слова после первой пишется с заглавной. Например, элемент управления вводом текста может называться txtUserEmailAddress.

Регистр Pascal

Для источников данных следует использовать регистр Pascal. Регистр Pascal иногда называют "верхним верблюжьим регистром". Как и верблюжий регистр, он удаляет все пробелы и делает первую букву слова заглавной. Однако, в отличие от верблюжьего регистра, в регистре Pascal первое слово также пишется с заглавной буквы. Например, распространенный источник данных в PowerApps это соединитель Microsoft Office 365 Users, который в вашем коде называется Office365Users.

Названия экранов

Названия экранов должны отражать назначение экрана, чтобы было легче ориентироваться в сложных приложениях в Power Apps Studio.

Менее очевидно то, что названия экранов читаются вслух с помощью программ чтения с экрана, которые нужны пользователям, которым необходимы специальные возможности для визуального восприятия. Поэтому крайне важно, чтобы вы использовали простой язык для обозначения своих экранов и чтобы названия содержали пробелы и не содержали сокращений. Кроме того, мы рекомендуем заканчивать название словом «Экран», чтобы понимать контекст при объявлении названия.

Ниже приведено несколько хороших примеров:

• Home_Screen или Home Screen
• Search_Screen или Search Screen

Эти примеры экранных имен менее понятны:

• Home
• LoaderScreen
• EmpProfDetails
• Thrive Help

Имена элементов управления

Все имена элементов управления на холсте должны использовать верблюжий регистр. Они должны начинаться с трехсимвольного дескриптора типа, за которым следует цель элемента управления. Такой подход помогает определить тип элемента управления и упрощает построение формул и поиск. Например, lblUserName указывает, что элемент управления является меткой.

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

Имя элемента управления	Аббревиатура
Индикатор событий	bdg
Button	btn
Элемент управления «Камера»	cam
Холст	can
Card	crd
Диаграммы	chr
Флажок выбора	chk
Коллекция	col
Поле со списком	cmb
Компонент	cmp
Контейнер	con
Даты	dte
Раскрывающийся список	drp
Форма	frm
Галерея	gal
Групповой	grp
Заголовок	hdr
Текст HTML	htm
Icon	ico
Изображения	img
Кнопка информации	Информация
Label	lbl
Ссылка	lnk
Поле со списком	lst
Микрофон	mic
Microsoft Stream	str
Форма раздела страницы	сек
Ввод с помощью пера	pen
Плитка Power BI	pbi
Индикатор выполнения	pbar
Rating	rtg
Редактор форматированного текста	rte
Фигуры (прямоугольник, круг и т. д.)	shp
Slider	sld
Табулированный список	tbl
Таблицу	tbl
Ввод текста	txt
Таймер	tmr
Toggle	tgl
Video	vid

Подробный список элементов управления и их свойства описаны в Справочнике по элементам управления.

Заметка

Имена элементов управления должны быть уникальными в приложении. Если элемент управления повторно используется на нескольких экранах, короткое имя экрана должно иметь суффикс. Например galBottomNavMenuHS, где "HS" означает "Главный экран". Такой подход упрощает создание ссылок на элемент управления в формулах на разных экранах.

Ниже приведено несколько плохих примеров:

• zipcode
• Next

Когда вы даете согласованные имена своим элементам управления, ваше приложение становится чище в представлении навигации, и ваш код тоже становится чище.

Имена источников данных

Когда вы добавляете источник данных в свое приложение, имя нельзя изменить в приложении Power Apps. Имя наследуется от исходного соединителя или информационных объектов, полученных из соединения.

Ниже приведено несколько примеров:

• Имя, унаследованное от исходного соединителя: соединитель «Office 365 Users» в вашем коде называется Office365Users.
• Информационные объекты, полученные из соединения: список Microsoft SharePoint с именем Employees возвращается из соединителя SharePoint. Поэтому имя источника данных в вашем коде — «Сотрудники». То же приложение Power Apps также может использовать тот же соединитель SharePoint для доступа к списку SharePoint с именем Contractors. В этом случае имя источника данных в коде — Contractors.

Дополнительные сведения о соединителях и соединениях см. в разделе Обзор соединителей приложений на основе холста для Power Apps.

Соединители для стандартных действий

В соединителях для стандартных действий, предоставляющих функции, таких как LinkedIn, имя источника данных и его операции используют регистр Pascal. Например, источник данных LinkedIn называется LinkedIn и имеет операцию с именем ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Настраиваемые соединители

Пользовательские соединители, используемые для подключения к пользовательским интерфейсам прикладного программирования (API), таким как службы или бизнес-API, созданные вашей компанией. Их может создать любой создатель в вашей среде. Мы рекомендуем использовать регистр Pascal для имени источника данных и его операций. Просто имейте в виду, что имя пользовательского соединителя и способ его отображения в PowerApps могут различаться.

Рассмотрим этот пример пользовательского соединителя с именем MS Auction Item Bid API.

Но когда вы создаете соединение из этого соединителя и добавляете его в свое приложение PowerApps как источник данных, оно отображается как AuctionItemBidAPI.

Чтобы выяснить причину, вы можете поискать в файле OpenAPI атрибут заголовка, содержащий текст Auction Item Bid API.

"info": {
    "version": "v1",
    "title": "Auction Item Bid API"
},

Power Apps удаляет все пробелы из значения этого атрибута и использует его в качестве имени вашего источника данных.

Совет

Мы рекомендуем вам изменить значение этого атрибута на имя в регистре Pascal, например AuctionItemBidAPI, и использовать его в качестве имени вашего пользовательского соединения. Таким образом, не будет путаницы. Измените это значение перед импортом файла OpenAPI для создания настраиваемого соединителя.

Заметка

Если вы используете параметр Создать с нуля вместо импорта существующего файла OpenAPI, PowerApps предложит вам ввести имя настраиваемого соединителя. Это имя будет использоваться как имя настраиваемого соединителя и как значение атрибута «title» внутри файла OpenAPI. Обязательно используйте имя в регистре Pascal, например AuctionItemBidAPI, чтобы обеспечить единообразие и простоту.

Таблицы данных Excel

PowerApps использует DataTables в Microsoft Excel для подключения к данным на листах Excel. Помните о следующих моментах при создании документов Excel в качестве источников данных:

• Давайте вашим таблицам DataTables описательные имена. Имя находится в приложении Power Apps, когда вы пишете код для подключения к нему.
• Используйте одну таблицу DataTable на лист.
• Давайте одно и то же имя таблице DataTable и листу.
• Используйте описательные имена столбцов в таблицах DataTables.
• Используйте регистр Pascal. Каждое слово имени таблицы DataTable должно начинаться с заглавной буквы, например EmployeeLeaveRequests.

Объекты без типов и динамические объекты

Имена переменных

Соглашения об именовании переменных в приложениях на основе холста важны для обеспечения читабельности, согласованности и ясности в ваших проектах Power Apps. Несмотря на то, что строгий стандарт не соблюдается, принятие согласованного соглашения об именовании в приложении на основе холста может облегчить вам и другим соавторам понимание, использование переменных и управление ими.

• Используйте верблюжий регистр, в котором первая буква каждого слова, за исключением первого слова, является заглавной.
• Выбирайте осмысленные и описательные имена, которые четко описывают назначение или содержание переменной. Избегайте слишком общих имен, таких как temp или var1. Вместо этого используйте описательные имена, такие как userEmail или totalAmount.
• Рассмотрите возможность использования префиксов или суффиксов для обозначения типа переменной. Например:
  • strUserName — для текстовой/строчной переменной
  • numTotalAmount — для числовой переменной
  • boolIsEnabled — для логической переменной
  • locVarName — для локальных переменных/переменных контекста
  • gblVarLoginUser — для глобальных переменных
• Решите, следует ли называть ваши переменные в форме единственного или множественного числа, и придерживайтесь этого соглашения. Например, согласованно используйте userCount или users.
• Избегайте использования зарезервированных слов или имен, которые могут конфликтовать с функциями Power Apps или ключевыми словами. Ознакомьтесь с документацией по Power Apps на предмет списка зарезервированных слов.
• Рассмотрите возможность использования префиксов, которые предоставляют контекст использования или области действия переменной. Например:
  • frm — для переменных форм
  • col — для коллекций
  • var — для переменных общего назначения
• Избегайте специальных символов. Сохраняйте имена буквенно-цифровыми и избегайте специальных символов и пробелов. Используйте только буквы и цифры.

Power Apps позволяет контекстным и глобальным переменным иметь одни и те же имена. Это может вызвать путаницу, поскольку в ваших формулах по умолчанию используются контекстные переменные, если только не применяется оператор устранения неоднозначности.

Чтобы избежать этой ситуации, следуйте этим соглашениям:

• Добавляйте префикс loc к контекстным переменным.
• Добавляйте префикс gbl к глобальным переменным.
• Имя после префикса должно указывать назначение/цель переменной. Можно использовать несколько слов, и их не обязательно разделять специальными символами, такими как пробелы или подчеркивания, если первая буква каждого слова является заглавной.
• Используйте верблюжий регистр. Начинайте имена переменных с префикса строчными буквами, а затем делайте заглавными первые буквы каждого слова в имени.

Эти примеры соответствуют стандартам и соглашениям:

• Глобальная переменная: gblFocusedBorderColor

• Переменная контекста:locSuccessMessage

• Переменная области:scpRadius

Эти примеры не соответствуют стандартам, и их сложнее понять:

• dSub
• rstFlds
• hideNxtBtn
• ttlOppCt
• cFV
• cQId

Избегайте коротких и загадочных имен переменных, таких как EID. Вместо этого используйте Use EmployeeId.

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

Имена коллекций

• Добавляйте описания к содержимому коллекций. Подумайте о том, что содержит коллекция и/или как она используется, а затем назовите ее соответствующим образом.
• Коллекции должны иметь префикс col.
• Имя после префикса должно указывать назначение или цель коллекции. Можно использовать несколько слов, и их не обязательно разделять пробелами или подчеркиваниями, если первая буква каждого слова является заглавной.
• Используйте верблюжий регистр. Начинайте имена коллекций с префикса «col» строчными буквами, а затем делайте заглавными первые буквы каждого слова в имени.

Эти примеры соответствуют соглашениям об именовании коллекций:

• colMenuItems
• colThriveApps

Эти примеры не соответствуют соглашениям об именовании коллекций:

• orderscoll
• tempCollection

Совет

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

Комментарии и документация

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

Существует два основных типа комментариев, призванных повысить ясность кода. Power Apps поддерживает два стиля комментариев: строковые комментарии, обозначаемые двойной косой чертой (//) для однострочных примечаний, и блочные комментарии заключенные внутри /* и */ для многострочных аннотаций.

Строчные комментарии

Добавление двойной косой черты (//) к любой строке кода в PowerApps обозначает остальную часть строки (включая //) в качестве комментария.

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

В этом примере показано использование строчных комментариев.

// ClearCollect function populates the Expenses2 collection with sample data
ClearCollect(
    Expenses2,
    // Entry 1: Client hosted meet and greet
    {
        Title: "Client hosted meet and greet:",
        ID: "4"
        // additional properties  
    }
)

Блочные комментарии

Текст, заключенный внутри /* и */, распознается как блочный комментарий. В отличие от строчных комментариев, которые применяются к одной строке, блочные комментарии могут охватывать несколько строк.

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

Для оптимальной организации кода рекомендуется добавлять комментарии после использования функции «Форматирование текста». Это полезно, если ваши комментарии предшествуют блоку кода.

/*
    Patch Operation to Insert Data:
    - Inserts a new employee record into the 'Employee' entity.
    - Adds corresponding department details to the 'Department' entity.
    Note: Ensure that foreign key relationships and dependencies are maintained for data integrity.
*/
Patch(
    Employee,
    Defaults(Employee),
    {
        FirstName: "John",
        LastName: "Doe",
        Position: "Software Developer"
    }
)

Функция «Форматирование текста» соответствует следующим правилам для существующих комментариев:

1. Если свойство начинается с блочного комментария, к нему будет добавлена следующая строка кода.
2. Если свойство начинается со строчного комментария, к нему не будет добавлена следующая строка кода. В противном случае код закомментируется.
3. Строчные и блочные комментарии в других местах свойства будут добавлены к предыдущей строке кода.

Не беспокойтесь о добавлении слишком большого количества комментариев или слишком длинных комментариев. Все комментарии удаляются, когда PowerApps создает пакет клиентского приложения. Таким образом, они не повлияют на размер пакета и не замедлят загрузку или время загрузки приложения.

Современный конструктор приложений с комментариями

В Power Apps для создателей считается лучшей практикой эффективно использовать функции комментирования как в Power Apps Studio, так и в современном конструкторе приложений.

Для оптимального взаимодействия с Power Apps Studio создателям рекомендуется добавлять комментарии следующими способами:

1. Щелкните правой кнопкой мыши многоточие («...») любого элемента в представлении в виде дерева.
2. Щелкните правой кнопкой мыши компонент в области холста.
3. Нажмите кнопку «Комментарии», расположенную на панели команд в правом верхнем углу экрана.

При упоминании коллег в комментариях рекомендуется использовать символ «@» и их имя. При этом отмеченному коллеге будет отправлено уведомление по электронной почте, что обеспечит быстрый доступ к комментарию. В тех случаях, когда отмеченный пользователь не имеет доступа к приложению, разработчику будет предложено поделиться с ним приложением.

Отступы и форматирование

В Power Apps отступы и форматирование имеют решающее значение для поддержания четкой и организованной структуры вашего приложения. Следуя рекомендациям, вы улучшите читаемость формул и элементов управления.

Строка формул

Отступы

Хотя Power Apps не обеспечивает строгих отступов, вы можете использовать пробелы для визуального разделения различных разделов формул. Нажмите клавишу пробела несколько раз, чтобы создать эффект отступа.

Разрывы строк

Вы можете разбить длинные формулы на несколько строк, чтобы улучшить читабельность. Нажмите Enter, чтобы создать разрыв строки в строке формул.

Используйте команду «Форматирование текста»

Команда «Форматирование текста» в строке формул предназначена для применения отступов, интервалов и разрывов строк к вашему коду в Power Apps. Используйте команду «Форматирование текста», чтобы установить единый стиль кодирования для всего приложения на основе холста, гарантируя более эффективный и устойчивый к ошибкам процесс разработки.

Следующий шаг

Оптимизация кода