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

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

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

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

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

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

Дело верблюда

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

Регистр Pascal

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

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

Выберите имена экрана, которые четко показывают назначение экрана, что упрощает навигацию по сложным приложениям в Power Apps Studio.

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

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

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

Снимок экрана: список имен экрана, которые соответствуют описанному шаблону.

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

  • Home
  • LoaderScreen
  • EmpProfDetails
  • Thrive Help

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

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

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

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

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

Замечание

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

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

  • zipcode
  • Next

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

Снимок экрана представления навигации с именами элементов управления, соответствующих описанному шаблону.

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

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

Далее приводятся некоторые примеры.

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

Дополнительные сведения о соединителях и подключениях см. в статье "Общие сведения о соединителях для приложений на основе холста".

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

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

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

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

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

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

Снимок экрана соединителя с именем MS Auction Item Bid API.

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

Снимок экрана с соединителем, на котором показано, что имя — AuctionItemBidAPI.

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

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

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

Подсказка

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

Замечание

Если вы используете команду Create из пустого параметра вместо импорта существующего файла OpenAPI, Power Apps запрашивает имя настраиваемого соединителя. Это имя является как именем настраиваемого соединителя, так и значением атрибута заголовка в файле OpenAPI. Используйте имя в регистре Pascal, например AuctionItemBidAPI, чтобы обеспечить единообразие и простоту.

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

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

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

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

Соглашения об именовании переменных в приложениях платформы Canvas важны для поддержания читаемости, согласованности и ясности в проектах 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. Вместо этого используйте EmployeeId.

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

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

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

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

  • colMenuItems
  • colThriveApps

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

  • orderscoll
  • tempCollection

Подсказка

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

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

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

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

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

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

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

Вот пример комментария к строке.

// 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. Строковые и блочные комментарии, встречающиеся в других местах свойства, добавляются к предыдущей строке кода.

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

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

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

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

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

Когда вы упоминаете коллегу в комментарии, используйте символ «@», за которым следует его имя. Это действие отправляет уведомление пользователю, который вы тегируете. Если у помеченного пользователя нет доступа к приложению, Power Apps предложит вам предоставить ему доступ к приложению.

Снимок экрана приложения о расходах, на котором показан человек, упомянутый с помощью @ в комментарии.

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

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

Отступы

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

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

Разбивайте длинные формулы на несколько строк, чтобы их было легче читать. Нажмите ВВОД, чтобы добавить в строку формул разрыв строки.

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

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

Снимок экрана Power Apps Studio с выделенной командой

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

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

  • Last updated on